Kestrelimplementacja serwera internetowego w ASP.NET Core

A ich autorstwa tom Dykstra, Chris Dostępi Stephen Halter

Kestrelto międzyplatformowy serwer sieci Web dla ASP.NET Core. Kestrelto serwer internetowy, który jest domyślnie dołączony i włączony w ASP.NET Core szablonów projektów.

Kestrel obsługuje następujące scenariusze:

  • HTTPS
  • HTTP/2 (z wyjątkiem systemu macOS † )
  • Nieprzezroczyste uaktualnienie używane do włączania funkcji WebSocket
  • Gniazda systemu Unix o wysokiej wydajności za usługą Nginx

†Protokół HTTP/2 będzie obsługiwany w systemie macOS w przyszłej wersji.

Kestrel Program jest obsługiwany na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Rozpoczęcie pracy

ASP.NET Core szablonów projektów Kestrel są domyślnie włączone. W program.cs metoda ConfigureWebHostDefaults wywołuje metodę 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>();
        });

Aby uzyskać więcej informacji na temat budowania hosta, zobacz sekcje Konfigurowanie hosta i Ustawienia konstruktora domyślnego w teście Ogólny host .NET w programie ASP.NET Core .

Opcjonalne certyfikaty klienta

Aby uzyskać informacje o aplikacjach, które muszą chronić podzbiór aplikacji przy użyciu certyfikatu, zobacz Opcjonalne certyfikaty klienta.

Dodatkowe zasoby

Uwaga

Od ASP.NET Core 5.0 transport Kestrel libuv usługi jest przestarzały. Transport libuv nie otrzymuje aktualizacji do obsługi nowych platform systemu operacyjnego, takich jak Windows ARM64, i zostanie usunięty w przyszłej wersji. Usuń wszystkie wywołania przestarzałej UseLibuv metody i zamiast tego użyj Kestrel domyślnego transportu gniazda.

Kestrelto międzyplatformowy serwer sieci Web dla ASP.NET Core. Kestrelto serwer internetowy, który jest domyślnie uwzględniany w szablonach ASP.NET Core projektu.

Kestrel obsługuje następujące scenariusze:

  • HTTPS
  • Nieprzezroczyste uaktualnienie używane do włączania funkcji WebSocket
  • Gniazda systemu Unix o wysokiej wydajności za usługą Nginx
  • HTTP/2 (z wyjątkiem systemu macOS † )

†Protokół HTTP/2 będzie obsługiwany w systemie macOS w przyszłej wersji.

Kestrel Program jest obsługiwany na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Obsługa protokołu HTTP/2

Protokół HTTP/2 jest dostępny dla ASP.NET Core aplikacji, jeśli są spełnione następujące wymagania podstawowe:

†Protokół HTTP/2 będzie obsługiwany w systemie macOS w przyszłej wersji. ‡Kestrelma ograniczoną obsługę protokołu HTTP/2 na Windows Server 2012 R2 i Windows 8.1. Obsługa jest ograniczona, ponieważ lista obsługiwanych mechanizmów szyfrowania TLS dostępnych w tych systemach operacyjnych jest ograniczona. Certyfikat wygenerowany przy użyciu algorytmu ECDSA (Elliptic Curve Digital Signature Algorithm) może być wymagany do zabezpieczenia połączeń TLS.

Jeśli połączenie HTTP/2 zostanie nawiązane, httpRequest.Protocol zgłasza HTTP/2 .

Począwszy od programu .NET Core 3.0, protokół HTTP/2 jest domyślnie włączony. Aby uzyskać więcej informacji na temat konfiguracji, zobacz Kestrel sekcje options i ListenOptions.Protocols.

Kiedy używać Kestrel zwrotnego serwera proxy

KestrelMoże być używany samodzielnie lub z odwrotnym serwerem proxy, takim jak Internet Information Services (IIS), Nginxlub Apache. Zwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel .

Kestrel używany jako brzegowy (internetowy) serwer internetowy:

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

Kestrel używane w konfiguracji zwrotnego serwera proxy:

Kestrel komunikuje się pośrednio z Internetem za pośrednictwem zwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja z odwrotnym serwerem proxy lub bez niego jest obsługiwaną konfiguracją hostingu.

Kestrel używany jako serwer brzegowy bez zwrotnego serwera proxy nie obsługuje współużytkowania tego samego adresu IP i portu między wieloma procesami. Gdy Kestrel program jest skonfigurowany do nasłuchiwać na porcie, obsługuje cały ruch dla tego portu niezależnie od Kestrel Host nagłówków żądań. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań Kestrel do adresu w unikatowym adresie IP i porcie.

Nawet jeśli zwrotny serwer proxy nie jest wymagany, dobrym wyborem może być użycie zwrotnego serwera proxy.

Zwrotny serwer proxy:

  • Może ograniczyć ujawniony publiczny obszar powierzchni hostowanej aplikacji.
  • Zapewnia dodatkową warstwę konfiguracji i ochrony.
  • Może lepiej integrować się z istniejącą infrastrukturą.
  • Uproszczenie równoważenia obciążenia i konfiguracji bezpiecznej komunikacji (HTTPS). Tylko odwrotny serwer proxy wymaga certyfikatu X.509, a ten serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.

Ostrzeżenie

Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego z nagłówkami przekazywania.

Kestrelw ASP.NET Core aplikacji

ASP.NET Core szablonów projektów Kestrel są domyślnie włączone. W program.cs metoda ConfigureWebHostDefaults wywołuje metodę 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>();
        });

Aby uzyskać więcej informacji na temat budowania hosta, zobacz sekcje Konfigurowanie hosta i Ustawienia konstruktora domyślnego w teście Ogólny host .NET w programie ASP.NET Core .

Aby zapewnić dodatkową konfigurację po wywołaniu ConfigureWebHostDefaults funkcji , użyj funkcji ConfigureKestrel :

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Kestrel Opcje

Serwer Kestrel internetowy ma opcje konfiguracji ograniczeń, które są szczególnie przydatne we wdrożeniach dostępnych z Internetu.

Ustaw ograniczenia właściwości Limits klasy KestrelServerOptions . Właściwość Limits zawiera wystąpienie klasy KestrelServerLimits .

W poniższych przykładach przestrzeń nazw jest Microsoft.AspNetCore.Server.Kestrel.Core następująca:

using Microsoft.AspNetCore.Server.Kestrel.Core;

W przykładach pokazanych w dalszej części tego artykułu Kestrel opcje są konfigurowane w kodzie języka C#. KestrelOpcje można również ustawić przy użyciu dostawcy konfiguracji. Na przykład dostawca konfiguracji plików może załadować konfigurację Kestrel z elementu lub appsettings.json appsettings.{ Plik Environment}.json:

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

Uwaga

KestrelServerOptions Konfigurację punktu końcowego i można konfigurować od dostawców konfiguracji. Pozostałą Kestrel konfigurację należy skonfigurować w kodzie języka C#.

Użyj jednej z następujących metod:

  • Skonfiguruj Kestrel w programie Startup.ConfigureServices :

    1. Wstrzyknąć IConfiguration wystąpienie klasy do klasy Startup . W poniższym przykładzie przyjęto założenie, że wstrzyknięta konfiguracja jest przypisana do Configuration właściwości .

    2. W Startup.ConfigureServices pliku Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

      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 budowania hosta:

    W pliku Program.cs Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

    // 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 metody działają z dowolnym dostawcą konfiguracji.

Limit czasu utrzymania aktywności

KeepAliveTimeout

Pobiera lub ustawia limit czasu podtrzymania aktywności. Wartość domyślna to 2 minuty.

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ń klienta

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalną liczbę współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu:

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 protokołu WebSockets). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.

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).

Maksymalny rozmiar treści żądania

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.

Zalecaną metodą przesłonięcia limitu w ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji dla każdego żądania:

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 dla określonego żądania w oprogramowania pośredniczącego:

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

Jeśli aplikacja skonfiguruje limit w żądaniu po tym, jak aplikacja zaczęła odczytywać żądanie, zgłaszany jest wyjątek. Istnieje właściwość, która wskazuje, czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest za opóźniona, IsReadOnly MaxRequestBodySize aby skonfigurować limit.

Gdy aplikacja jest poza procesem w module ASP.NET Core,limit rozmiaru treści żądania jest wyłączony, ponieważ usługi IIS już Kestrel ustawiają limit.

Minimalna szybkość danych treści żądania

MinRequestBodyDataRate MinResponseDataRate

Kestrel Sprawdza co sekundę, czy dane docierają z określoną szybkością w bajtach na sekundę. Jeśli szybkość spadnie poniżej wartości minimalnej, zostanie upuszczany czas połączenia. Okres prolongaty to czas, przez który klient może zwiększyć szybkość wysyłania do minimum. W tym czasie ta szybkość nie jest Kestrel sprawdzana. Okres prolongaty pomaga uniknąć porzucania połączeń, które początkowo wysyłają dane z wolnym tempem z powodu powolnego uruchamiania protokołu TCP.

Domyślna minimalna szybkość to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.

Minimalna stawka ma również zastosowanie do odpowiedzi. Kod do ustawienia limitu żądań i limitu odpowiedzi jest taki sam z wyjątkiem właściwości RequestBody lub Response w nazwach właściwości i interfejsu.

Oto przykład, który pokazuje, jak skonfigurować minimalne stawki danych w programie 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);
})

Zastąp limity minimalnej szybkości na żądanie w oprogramowania pośredniczącego:

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

Odwołanie w poprzedniej próbce nie jest obecne w przypadku żądań HTTP/2, ponieważ modyfikowanie limitów szybkości dla 1 żądania zwykle nie jest obsługiwane w przypadku protokołu HTTP/2 ze względu na obsługę multipleksowania żądań przez IHttpMinResponseDataRateFeature HttpContext.Features protokół. Jednak nadal jest obecny dla żądań HTTP/2, ponieważ limit szybkości odczytu nadal można całkowicie wyłączyć dla każdego żądania, ustawiając nawet dla żądania IHttpMinRequestBodyDataRateFeature HttpContext.Features IHttpMinRequestBodyDataRateFeature.MinDataRate null HTTP/2. Próba odczytu lub próby ustawienia jej na wartość inną niż spowoduje zgłoszenie żądania IHttpMinRequestBodyDataRateFeature.MinDataRate null NotSupportedException HTTP/2.

Limity szybkości dla całego serwera skonfigurowane za pośrednictwem nadal mają zastosowanie zarówno do KestrelServerOptions.Limits połączeń HTTP/1.x, jak i HTTP/2.

Limit czasu nagłówków żądań

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez który serwer spędza na otrzymywaniu nagłówków żądań. Wartość domyślna to 30 sekund.

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łączenie

Http2.MaxStreamsPerConnection ogranicza liczbę współbieżnych strumieni żądań na połączenie HTTP/2. Nadmiarowe strumienie są odrzucane.

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

Wartość domyślna to 100.

Rozmiar tabeli nagłówka

Dekoder HPACK dekompresuje nagłówki HTTP dla połączeń HTTP/2. Http2.HeaderTableSize ogranicza rozmiar tabeli kompresji nagłówka używanej przez dekoder HPACK. Wartość jest dostarczana w oktetach i musi być większa od zera (0).

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

Wartość domyślna to 4096.

Maksymalny rozmiar ramki

Http2.MaxFrameSize wskazuje maksymalny dozwolony rozmiar ładunku ramki połączenia HTTP/2 odebranego lub wysłanego przez serwer. Wartość jest dostarczana w oktetach i musi zawierać się w wartościach od 2^14 (16 384) do 2^24-1 (16 777 215).

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

Wartość domyślna to 2^14 (16 384).

Maksymalny rozmiar nagłówka żądania

Http2.MaxRequestHeaderFieldSize wskazuje maksymalny dozwolony rozmiar w oktetach wartości nagłówka żądania. Ten limit dotyczy zarówno nazwy, jak i wartości w ich skompresowanych i nieskompresowanych reprezentacjach. Wartość musi być większa od zera (0).

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

Wartość domyślna to 8192.

Początkowy rozmiar okna połączenia

Http2.InitialConnectionWindowSize wskazuje maksymalną ilość danych treści żądania w bajtach buforów serwera jednocześnie zagregowanych dla wszystkich żądań (strumieni) na połączenie. Żądania są również ograniczone przez Http2.InitialStreamWindowSize . Wartość musi być większa lub równa 65 535 i mniejsza niż 2^31 (2 147 483 648).

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

Wartość domyślna to 128 KB (131 072).

Początkowy rozmiar okna strumienia

Http2.InitialStreamWindowSize wskazuje maksymalną ilość danych treści żądania w bajtach buforów serwera jednocześnie na żądanie (strumień). Żądania są również ograniczone przez Http2.InitialConnectionWindowSize . Wartość musi być większa lub równa 65 535 i mniejsza niż 2^31 (2 147 483 648).

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

Wartość domyślna to 96 KB (98 304).

Przyczepy

Przyczepki HTTP są podobne do nagłówków HTTP, z tą różnicą, że są wysyłane po wysłaniu treści odpowiedzi. W przypadku usług IIS HTTP.sys obsługiwane są tylko przyczepki odpowiedzi HTTP/2.

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

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

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

W powyższym przykładowym kodzie:

  • SupportsTrailers Zapewnia, że dla odpowiedzi są obsługiwane przyczepki.
  • DeclareTrailer Dodaje podaną nazwę przyczepki do Trailer nagłówka odpowiedzi. Deklarowanie przyczepek odpowiedzi jest opcjonalne, ale zalecane. Jeśli DeclareTrailer zostanie wywołana, musi on znajdować się przed wysłaniem nagłówków odpowiedzi.
  • AppendTrailer dołącza przyczepkę.

Reset

Resetowanie umożliwia serwerowi zresetowanie żądania HTTP/2 z określonym kodem błędu. Żądanie zresetowania jest uznawane za przerwane.

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

Reset W poprzednim przykładzie kodu określono INTERNAL_ERROR kod błędu. Aby uzyskać więcej informacji na temat kodów błędów HTTP/2, odwiedź sekcję Kod błędu specyfikacji HTTP/2.

Synchroniczne operacje we/wy

AllowSynchronousIO określa, czy synchroniczne we/wy są dozwolone dla żądania i odpowiedzi. Wartość domyślna to false.

Ostrzeżenie

Duża liczba blokujących synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada. Włącz tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.

Poniższy przykład umożliwia synchroniczne we/wy:

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

Aby uzyskać informacje o innych Kestrel opcjach i limitach, zobacz:

Konfiguracja punktu końcowego

Domyślnie program ASP.NET Core z:

  • http://localhost:5000
  • https://localhost:5001 (jeśli jest obecny lokalny certyfikat dewelopera)

Określ adresy URL przy użyciu:

  • ASPNETCORE_URLS zmienna środowiskowa.
  • --urls argument wiersza polecenia.
  • urls klucz konfiguracji hosta.
  • UseUrls metoda rozszerzenia.

Wartością zapewnianą przy użyciu tych metod może być co najmniej jeden punkt końcowy HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).

Aby uzyskać więcej informacji na temat tych metod, zobacz Server URLs and Override configuration (Adresy URL serwera i przesłanianie konfiguracji).

Zostanie utworzony certyfikat dewelopera:

Niektóre przeglądarki wymagają udzielenia jawnego uprawnienia do zaufania lokalnemu certyfikatowi dewelopera.

Project konfigurują aplikacje do domyślnego uruchamiania przy użyciu protokołu HTTPS i obsługują przekierowywanie HTTPS oraz usługi HSTS.

Wywołaj Listen wywołanie metody lub , aby skonfigurować ListenUnixSocket KestrelServerOptions prefiksy adresów URL i porty dla elementu Kestrel .

UseUrls, argument wiersza polecenia, klucz konfiguracji hosta i zmienna środowiskowa również działają, ale mają ograniczenia zanotowe w dalszej części tej sekcji (domyślny certyfikat musi być dostępny dla konfiguracji punktu --urls urls ASPNETCORE_URLS końcowego HTTPS).

KestrelServerOptions Konfiguracji:

ConfigureEndpointDefaults(Akcja <ListenOptions> )

Określa konfigurację do Action uruchomienia dla każdego określonego punktu końcowego. Wywołanie ConfigureEndpointDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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

Uwaga

Punkty końcowe utworzone przez wywołanie Listen przed wywołaniem ConfigureEndpointDefaults nie będą mieć zastosowanych wartości domyślnych.

ConfigureHttpsDefaults(Akcja <HttpsConnectionAdapterOptions> )

Określa konfigurację do Action uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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 będą mieć zastosowanych wartości domyślnych.

Configure(IConfiguration)

Tworzy modułu ładującego konfiguracji do Kestrel konfigurowania, który przyjmuje IConfiguration jako dane wejściowe. Konfiguracja musi być w zakresie sekcji konfiguracji dla Kestrel programu .

ListenOptions.UseHttps

Skonfiguruj Kestrel do używania protokołu HTTPS.

ListenOptions.UseHttps Rozszerzenia:

  • UseHttps: skonfiguruj Kestrel do używania protokołu HTTPS z certyfikatem domyślnym. Zgłasza wyjątek, jeśli nie skonfigurowano certyfikatu domyślnego.
  • 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 Parametry:

  • filename to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
  • configureOptionsto element Action do konfigurowania . HttpsConnectionAdapterOptions Zwraca wartość ListenOptions .
  • storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
  • subject to nazwa podmiotu certyfikatu.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
  • location to lokalizacja magazynu, z których ma być ładowany certyfikat.
  • serverCertificate to certyfikat X.509.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS. Należy podać co najmniej certyfikat domyślny.

Obsługiwane konfiguracje opisane poniżej:

  • Brak konfiguracji
  • Zastępowanie domyślnego certyfikatu z konfiguracji
  • Zmienianie wartości domyślnych w kodzie

Brak konfiguracji

Kestrel Nasłuchuje http://localhost:5000 na i https://localhost:5001 (jeśli jest dostępny domyślny certyfikat).

Zastępowanie domyślnego certyfikatu z konfiguracji

CreateDefaultBuilder Domyślnie Configure(context.Configuration.GetSection("Kestrel")) program wywołuje usługę w celu załadowania Kestrel konfiguracji. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel . Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

W poniższym appsettings.json przykładzie:

  • Ustaw wartość AllowInvalid na , aby zezwolić na używanie nieprawidłowych certyfikatów (na przykład true certyfikatów z podpisem własnym).
  • Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie), powraca do certyfikatu zdefiniowanego w obszarze Certyfikat domyślny lub certyfikat > dewelopera.
{
  "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 używania ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów. Na przykład domyślny certyfikat certyfikatów można > określić jako:

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

Uwagi dotyczące schematu:

  • W nazwach punktów końcowych nie jest uwzględniania ich litera. Na przykład wartości HTTPS i Https są prawidłowe.
  • Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu, z tą różnicą, że jest Urls on ograniczony do pojedynczej wartości.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego Urls poziomu, a nie dodając do nich. Punkty końcowe zdefiniowane w kodzie za pośrednictwem programu kumulują się z Listen punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
  • Sekcja Certificate jest opcjonalna. Jeśli sekcja nie zostanie określona, zostaną użyte wartości domyślne Certificate zdefiniowane we wcześniejszych scenariuszach. Jeśli wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie można uruchomić.
  • Sekcja Certificate obsługuje certyfikaty Hasło – ścieżki i – Magazyn podmiotu.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, o ile nie powodują konfliktów portów.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) Zwraca metodę z metodą , która może służyć do uzupełnienia skonfigurowanych ustawień KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) punktu końcowego:
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, aby kontynuować iterowanie po istniejącym ładowaniu, takim jak ten dostarczony przez program CreateDefaultBuilder .

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach metody , aby Endpoint można było odczytać ustawienia niestandardowe.
  • Wiele konfiguracji może zostać załadowanych przez wywołanie options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją. Używana jest tylko ostatnia konfiguracja, chyba że Load zostanie jawnie wywołana w poprzednich wystąpieniach. Metapakiet nie jest wywołany, aby można było zastąpić jego Load domyślną sekcję konfiguracji.
  • KestrelConfigurationLoader Odzwierciedla Listen rodzinę interfejsów API z jako przeciążenia, więc punkty końcowe kodu i konfiguracji mogą być skonfigurowane KestrelServerOptions Endpoint w tym samym miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Zmienianie wartości domyślnych w kodzie

ConfigureEndpointDefaults I może służyć do zmiany ustawień domyślnych dla i , w tym zastępowania certyfikatu ConfigureHttpsDefaults ListenOptions HttpsConnectionAdapterOptions domyślnego określonego w wcześniejszym scenariuszu. ConfigureEndpointDefaults i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem jakichkolwiek punktów końcowych.

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

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

Kestrel obsługa SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i tym samym porcie. Aby funkcja SNI działała, klient wysyła nazwę hosta bezpiecznej sesji do serwera podczas ugody TLS, dzięki czemu serwer może podać prawidłowy certyfikat. Klient używa zaszyfrowanego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po ugodzie TLS.

Kestrel obsługuje interfejs SNI za ServerCertificateSelector pośrednictwem wywołania zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu.

Obsługa SNI wymaga:

  • Uruchamianie na platformie docelowej netcoreapp2.1 lub nowszej. W net461 dniu lub później wywołanie zwrotne jest wywoływane, ale zawsze jest name null . Parametr jest również wtedy, gdy klient nie poda parametru nazwy name null hosta w uściśliwce TLS.
  • Wszystkie witryny internetowe działają w tym samym Kestrel wystąpieniu. Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera 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ń

Wywołanie UseConnectionLogging w celu emitowania dzienników poziomu debugowania dla komunikacji na poziomie bajtów w połączeniu. Rejestrowanie połączeń jest przydatne w przypadku rozwiązywania problemów z komunikacją niskiego poziomu, takich jak szyfrowanie TLS i za proxy. Jeśli UseConnectionLogging zostanie umieszczony przed , UseHttps szyfrowany ruch jest rejestrowany. Jeśli UseConnectionLogging zostanie umieszczony po , UseHttps odszyfrowany ruch jest rejestrowany.

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

Wiązanie z gniazdem TCP

Metoda Listen wiąże się z gniazdem TCP, a lambda opcji zezwala na konfigurację certyfikatu X.509:

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

W przykładzie skonfigurowano protokół HTTPS dla punktu końcowego za ListenOptions pomocą . Użyj tego samego interfejsu API, aby skonfigurować Kestrel inne ustawienia dla określonych punktów końcowych.

W systemie Windows certyfikaty z podpisem własnym można tworzyć przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby uzyskać nieobsługiwany przykład, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć przy użyciu programu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwać na gnieździe systemu Unix za pomocą polecenia w celu poprawy wydajności przy użyciu ListenUnixSocket systemu Nginx, jak pokazano w poniższym przykładzie:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • W pliku konfiguracji serwera Nginx ustaw server > location > proxy_pass wpis na http://unix:/tmp/{KESTREL SOCKET}:/; wartość . {KESTREL SOCKET} to nazwa gniazda dostarczonego dla ListenUnixSocket (na przykład kestrel-test.sock w poprzednim przykładzie).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład chmod go+w /tmp/kestrel-test.sock ).

Port 0

Po podano 0 numer portu dynamicznie wiąże się z Kestrel dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port Kestrel jest faktycznie powiązany w czasie wykonywania:

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, na którym można uzyskać do aplikacji:

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

Ograniczenia

Skonfiguruj punkty końcowe przy użyciu następujących metod:

  • UseUrls
  • --urls argument wiersza polecenia
  • urls klucz konfiguracji hosta
  • ASPNETCORE_URLS zmienna środowiskowa

Te metody są przydatne do pracy kodu z serwerami innymi niż Kestrel . Należy jednak pamiętać o następujących ograniczeniach:

  • Przy użyciu tych metod nie można używać protokołu HTTPS, chyba że w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat (na przykład przy użyciu konfiguracji lub pliku konfiguracji, jak pokazano wcześniej KestrelServerOptions w tym temacie).
  • Gdy oba podejścia Listen i UseUrls są używane jednocześnie, punkty końcowe Listen UseUrls przesłaniają punkty końcowe.

Konfiguracja punktu końcowego usług IIS

W przypadku korzystania z usług IIS powiązania adresów URL dla powiązań przesłonięcia usług IIS są ustawiane przez wartość Listen lub UseUrls . Aby uzyskać więcej informacji, zobacz temat ASP.NET Core Module.

ListenOptions.Protocols

Właściwość ustanawia protokoły HTTP ( ) włączone w punkcie końcowym Protocols połączenia lub na HttpProtocols serwerze. Przypisz wartość do Protocols właściwości z HttpProtocols wyli roku.

HttpProtocols wartość wyli Dozwolony protokół połączenia
Http1 Tylko PROTOKÓŁ HTTP/1.1. Może być używany z lub bez użycia TLS.
Http2 Tylko HTTP/2. Można używać bez użycia systemu TLS tylko wtedy, gdy klient obsługuje tryb wcześniejszej wiedzy.
Http1AndHttp2 HTTP/1.1 i HTTP/2. Protokół HTTP/2 wymaga od klienta wybrania protokołu HTTP/2 podczas negocjacji protokołu warstwy aplikacji (ALPN) protokołu TLS. W przeciwnym razie połączenie zostanie domyślnie na nawiązaniu połączenia HTTP/1.1.

Wartość ListenOptions.Protocols domyślna dla dowolnego punktu końcowego to HttpProtocols.Http1AndHttp2 .

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

  • TLS w wersji 1.2 lub nowszej
  • Renegotiation disabled (Ponowne negocjowanie jest wyłączone)
  • Kompresja wyłączona
  • Minimalne rozmiary efemerów wymiany kluczy:
    • Krzywa wielokropka Diffie-Hellman (ECDHE) [ RFC4492: ] minimum 224 bity
    • Skończony czas Diffie-Hellman (DHE): [ TLS12 ] minimum 2048 bitów
  • Zestaw szyfrowania nie jest zabroniony.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE] z krzywą wielokropkową P-256 [ FIPS186 ] jest obsługiwana domyślnie.

Poniższy przykład zezwala na połączenia HTTP/1.1 i HTTP/2 na porcie 8000. Połączenia są zabezpieczone przez zabezpieczenia TLS przy użyciu podanego certyfikatu:

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

Użyj oprogramowania pośredniczącego połączeń, aby w razie potrzeby filtrować uściśle TLS dla poszczególnych połączeń dla określonych szyfrów.

Poniższy przykład zgłasza NotSupportedException wyjątek dla dowolnego algorytmu szyfrowania, który nie jest przez aplikację wspierany. Alternatywnie zdefiniuj i porównaj ITlsHandshakeFeature.CipherAlgorithm z listą akceptowalnych mechanizmów szyfrowania.

Szyfrowanie nie jest używane z algorytmem szyfrowania CipherAlgorithmType.Null.

// 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ą IConnectionBuilder wyrażenia 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 można użyć do filtrowania uściślień CipherSuitesPolicy TLS dla 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 konfiguracji

CreateDefaultBuilder Domyślnie serverOptions.Configure(context.Configuration.GetSection("Kestrel")) program wywołuje usługę , aby Kestrel załadować konfigurację.

W poniższym appsettings.json przykładzie protokół HTTP/1.1 jest ustanawiany jako domyślny protokół połączenia dla wszystkich punktów końcowych:

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

W poniższym appsettings.json przykładzie ustanawiany jest protokół połączenia HTTP/1.1 dla określonego punktu końcowego:

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

Protokoły określone w kodzie zastępują wartości ustawione przez konfigurację.

Prefiksy adresów URL

W przypadku UseUrls korzystania z argumentu wiersza polecenia, klucza konfiguracji hosta lub zmiennej środowiskowej prefiksy adresów URL mogą być w --urls urls dowolnym z następujących ASPNETCORE_URLS formatów.

Prawidłowe są tylko prefiksy adresów URL PROTOKOŁU HTTP. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy UseUrls użyciu .

  • Adres IPv4 z numerem portu

    http://65.55.39.10:80/
    

    0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

  • Adres IPv6 z numerem portu

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

    [::] jest odpowiednikiem protokołu IPv6 protokołu 0.0.0.0 IPv4.

  • Nazwa hosta z numerem portu

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

    Nazwy * hostów, , i , nie są + specjalne. Wszystko, co nie jest rozpoznawane jako prawidłowy adres IP lub wiąże się ze wszystkimi adresami localhost IP IPv4 i IPv6. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core na tym samym porcie, użyj serwera HTTP.sys lub odwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache.

    Ostrzeżenie

    Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego z nagłówkami przekazywania.

  • Nazwa localhost hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

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

    Gdy jest określony, próbuje powiązać z interfejsami sprzężenia zwrotnego localhost Kestrel IPv4 i IPv6. Jeśli żądany port jest w użyciu przez inną usługę w obu interfejsach sprzężenia zwrotnego, Kestrel uruchomienie nie powiedzie się. Jeśli którykolwiek z interfejsów sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej nie jest obsługiwany protokół IPv6), program Kestrel rejestruje ostrzeżenie.

Filtrowanie hostów

Program Kestrel obsługuje konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , ale w dużej mierze Kestrel ignoruje nazwę hosta. Host localhost to specjalny przypadek używany do powiązania z adresami sprzężenia zwrotnego. Dowolny host inny niż jawny adres IP jest wiązany ze wszystkimi publicznymi adresami IP. Host Nagłówki nie są weryfikowane.

Aby obejść ten problem, użyj oprogramowania pośredniczącego filtrowania hostów. Oprogramowanie pośredniczące filtrowania hostów jest dostarczane przez pakiet Microsoft.AspNetCore.HostFiltering, który jest niejawnie dostarczany ASP.NET Core aplikacji. Oprogramowanie pośredniczące jest dodawane przez program CreateDefaultBuilder , który wywołuje : 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>();
}

Oprogramowanie pośredniczące filtrowania hosta jest domyślnie wyłączone. Aby włączyć oprogramowanie pośredniczące, zdefiniuj AllowedHosts klucz w appsettings.json / elementach appsettings. <EnvironmentName> . json. Wartość jest rozdzielaną średnikami listą nazw hostów bez numerów portów:

appsettings.json:

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

Uwaga

Oprogramowanie pośredniczące Nagłówki dalej ma również AllowedHosts opcję . Oprogramowanie pośredniczące Nagłówki dalej i oprogramowanie pośredniczące filtrowania hostów mają podobne funkcje w różnych scenariuszach. Ustawienie oprogramowania pośredniczącego z nagłówkami przekazywania jest odpowiednie, gdy nagłówek nie jest zachowywany podczas przekazywania żądań za pomocą zwrotnego serwera AllowedHosts Host proxy lub usługi równoważenia obciążenia. Ustawienie oprogramowania pośredniczącego filtrowania hosta jest odpowiednie, gdy jest używane jako publiczny serwer brzegowy lub gdy AllowedHosts Kestrel nagłówek jest bezpośrednio Host przesyłany dalej.

Aby uzyskać więcej informacji na temat oprogramowania pośredniczącego nagłówków przesyłania dalej, zobacz Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .

Konfiguracja transportu Libuv

W przypadku projektów, które wymagają użycia biblioteki Libuv ( UseLibuv ):

  • Dodaj zależność Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv dla pakietu do pliku projektu aplikacji:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Wywołaj UseLibuv wywołanie dla 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>();
                });
    }
    

Opróżnianie żądania HTTP/1.1

Otwieranie połączeń HTTP jest czasochłonne. W przypadku protokołu HTTPS jest on również intensywnie obciążany zasobami. W związku z tym program próbuje ponownie użyć połączeń dla Kestrel protokołu HTTP/1.1. Treść żądania musi być w pełni wykorzystana, aby umożliwić ponowne użycie połączenia. Aplikacja nie zawsze zużywa treść żądania, taką jak żądania, w których serwer zwraca przekierowanie POST lub odpowiedź 404. W przypadku POST -redirect:

  • Klient mógł już wysłać część POST danych.
  • Serwer zapisuje odpowiedź 301.
  • Nie można użyć połączenia dla nowego żądania, dopóki dane z poprzedniej treści żądania nie POST zostaną w pełni odczytane.
  • Kestrel próbuje opróżnić treść żądania. Opróżnianie treści żądania oznacza odczytywanie i odrzucanie danych bez ich przetwarzania.

Proces opróżniania umożliwia przechodzenie między zezwoleniem na ponowne użycie połączenia a czasem, który zajmuje opróżnienie pozostałych danych:

  • Opróżnianie ma limit czasu 5 sekund, którego nie można skonfigurować.
  • Jeśli wszystkie dane określone przez nagłówek lub nie zostały odczytane przed limitem Content-Length Transfer-Encoding czasu, połączenie zostanie zamknięte.

Czasami możesz chcieć zakończyć żądanie natychmiast, przed lub po napisanie odpowiedzi. Na przykład klienci mogą mieć restrykcyjne limity danych, więc ograniczenie przekazanych danych może być priorytetem. W takich przypadkach, aby zakończyć żądanie, wywołaj httpContext.Abort z kontrolera, Razor strony lub oprogramowania pośredniczącego.

Istnieją zastrzeżenia do wywoływania Abort funkcji :

  • Tworzenie nowych połączeń może być powolne i kosztowne.
  • Nie ma gwarancji, że klient odczytał odpowiedź przed zamknięciem połączenia.
  • Wywoływanie Abort powinno być rzadkie i zarezerwowane w przypadku poważnych błędów, a nie typowych błędów.
    • Wywołaj Abort tylko wtedy, gdy trzeba rozwiązać określony problem. Na przykład wywołaj wywołanie , jeśli złośliwi klienci próbują uzyskać dane lub gdy w kodzie klienta znajduje się usterka, która Abort powoduje duże lub wiele POST żądań.
    • Nie wywołuj typowych sytuacji błędów, takich Abort jak HTTP 404 (nie znaleziono).

Wywołanie httpResponse.CompleteAsync przed wywołaniem zapewnia, że Abort serwer zakończył zapisywanie odpowiedzi. Jednak zachowanie klienta nie jest przewidywalne i może nie odczytać odpowiedzi przed przerwaniem połączenia.

Ten proces różni się w przypadku protokołu HTTP/2, ponieważ protokół obsługuje przerywanie poszczególnych strumieni żądań bez zamykania połączenia. Limit czasu opróżnienia pięciu sekund nie ma zastosowania. Jeśli po zakończeniu odpowiedzi istnieją nieprzeczytane dane treści żądania, serwer wysyła ramkę HTTP/2 RST. Dodatkowe ramki danych treści żądania są ignorowane.

Jeśli to możliwe, lepiej jest, aby klienci korzystali z nagłówka żądania Expect: 100-continue i czekali, aż serwer odpowie przed rozpoczęciem wysyłania treści żądania. Daje to klientowi możliwość zbadania odpowiedzi i przerwania przed wysłaniem niepotrzebnych danych.

Dodatkowe zasoby

Kestrelto międzyplatformowy serwer sieci Web dla ASP.NET Core. Kestrelto serwer internetowy, który jest domyślnie uwzględniany w szablonach ASP.NET Core projektu.

Kestrel obsługuje następujące scenariusze:

  • HTTPS
  • Nieprzezroczyste uaktualnienie używane do włączania funkcji WebSocket
  • Gniazda systemu Unix o wysokiej wydajności za usługą Nginx
  • HTTP/2 (z wyjątkiem systemu † macOS)

†Protokół HTTP/2 będzie obsługiwany w systemie macOS w przyszłej wersji.

Kestrel Program jest obsługiwany na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Obsługa protokołu HTTP/2

Protokół HTTP/2 jest dostępny dla ASP.NET Core aplikacji, jeśli są spełnione następujące wymagania podstawowe:

†Protokół HTTP/2 będzie obsługiwany w systemie macOS w przyszłej wersji. ‡Kestrelma ograniczoną obsługę protokołu HTTP/2 na Windows Server 2012 R2 i Windows 8.1. Obsługa jest ograniczona, ponieważ lista obsługiwanych mechanizmów szyfrowania TLS dostępnych w tych systemach operacyjnych jest ograniczona. Do zabezpieczenia połączeń TLS może być wymagany certyfikat wygenerowany przy użyciu algorytmu ECDSA (Elliptic Curve Digital Signature Algorithm).

Jeśli zostanie nawiązane połączenie HTTP/2, protokół HttpRequest.Protocol zgłasza błąd HTTP/2 .

Protokół HTTP/2 jest domyślnie wyłączony. Aby uzyskać więcej informacji na temat konfiguracji, zobacz Kestrel sekcje options i ListenOptions.Protocols.

Kiedy używać Kestrel zwrotnego serwera proxy

KestrelMoże być używany samodzielnie lub z odwrotnym serwerem proxy, takim jak Internet Information Services (IIS), Nginxlub Apache. Zwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel .

Kestrel używany jako brzegowy (internetowy) serwer internetowy:

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

Kestrel używane w konfiguracji zwrotnego serwera proxy:

Kestrel komunikuje się pośrednio z Internetem za pośrednictwem zwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja z odwrotnym serwerem proxy lub bez niego jest obsługiwaną konfiguracją hostingu.

Kestrel używany jako serwer brzegowy bez zwrotnego serwera proxy nie obsługuje współużytkowania tego samego adresu IP i portu między wieloma procesami. Gdy Kestrel program jest skonfigurowany do nasłuchiwać na porcie, obsługuje cały ruch dla tego portu niezależnie od Kestrel Host nagłówków żądań. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań do usługi Kestrel na unikatowy adres IP i port.

Nawet jeśli zwrotny serwer proxy nie jest wymagany, dobrym wyborem może być użycie zwrotnego serwera proxy.

Zwrotny serwer proxy:

  • Może ograniczyć dostępny publiczny obszar powierzchni aplikacji, które hostuje.
  • Zapewnia dodatkową warstwę konfiguracji i ochrony.
  • Może lepiej integrować się z istniejącą infrastrukturą.
  • Uproszczenie równoważenia obciążenia i konfiguracji bezpiecznej komunikacji (HTTPS). Tylko odwrotny serwer proxy wymaga certyfikatu X.509, a ten serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.

Ostrzeżenie

Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego znagłówkami przekazywania.

Jak używać w Kestrel aplikacjach ASP.NET Core aplikacji

Microsoft.AspNetCore.Server. Kestrel pakiet jest zawarty w Microsoft.AspNetCore.App metapakiecie.

ASP.NET Core szablonu projektu Kestrel są domyślnie używać. W pliku Program.cs kod szablonu wywołuje CreateDefaultBuilder , który wywołuje w UseKestrel tle.

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

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

Aby uzyskać więcej informacji CreateDefaultBuilder na temat i budowania hosta, zobacz sekcję Konfigurowanie hosta w programie ASP.NET Core Web Host .

Aby zapewnić dodatkową konfigurację po wywołaniu CreateDefaultBuilder funkcji , użyj opcji 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 wywołania w celu CreateDefaultBuilder skonfigurowania hosta, wywołaj wywołanie UseKestrel przed wywołaniem ConfigureKestrel funkcji :

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

    host.Run();
}

Kestrel Opcje

Serwer Kestrel internetowy ma opcje konfiguracji ograniczeń, które są szczególnie przydatne we wdrożeniach dostępnych z Internetu.

Ustaw ograniczenia właściwości Limits klasy KestrelServerOptions . Właściwość Limits zawiera wystąpienie klasy KestrelServerLimits .

W poniższych przykładach jest używana przestrzeń Microsoft.AspNetCore.Server.Kestrel.Core nazw :

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel Opcje , które zostały skonfigurowane w kodzie C# w poniższych przykładach, można również ustawić przy użyciu dostawcy konfiguracji. Na przykład dostawca konfiguracji plików może załadować Kestrel konfigurację z elementu appsettings.json lub appsettings.{ Plik Environment}.json:

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

Użyj jednej z następujących metod:

  • Skonfiguruj Kestrel w programie Startup.ConfigureServices :

    1. Wstrzyknąć IConfiguration wystąpienie klasy do klasy Startup . W poniższym przykładzie przyjęto założenie, że wstrzyknięta konfiguracja jest przypisana do Configuration właściwości .

    2. W Startup.ConfigureServices pliku Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

      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 budowania hosta:

    W pliku Program.cs Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

    // 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 metody działają z dowolnym dostawcą konfiguracji.

Limit czasu utrzymania aktywności

KeepAliveTimeout

Pobiera lub ustawia limit czasu keep-alive. Wartość domyślna to 2 minuty.

.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ń klienta

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalną liczbę współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu:

.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 Protokołu WebSocket). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.

.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).

Maksymalny rozmiar treści żądania

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.

Zalecaną metodą przesłonięcia limitu w ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji dla każdego żądania:

.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 dla określonego żądania w oprogramowania pośredniczącego:

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

Jeśli aplikacja skonfiguruje limit w żądaniu po tym, jak aplikacja zaczęła odczytywać żądanie, zgłaszany jest wyjątek. Istnieje właściwość, która wskazuje, czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest za opóźniona, IsReadOnly MaxRequestBodySize aby skonfigurować limit.

Gdy aplikacja jest poza procesem w module ASP.NET Core,limit rozmiaru treści żądania jest wyłączony, ponieważ usługi IIS już Kestrel ustawiają limit.

Minimalna szybkość danych treści żądania

MinRequestBodyDataRate MinResponseDataRate

Kestrel sprawdza co sekundę, jeśli dane docierają z określoną szybkością w bajtach na sekundę. Jeśli szybkość spadnie poniżej wartości minimalnej, zostanie upuszczany czas połączenia. Okres prolongaty to czas, przez który klient może zwiększyć szybkość wysyłania do minimum. W tym czasie ta szybkość nie jest Kestrel sprawdzana. Okres prolongaty pomaga uniknąć porzucania połączeń, które początkowo wysyłają dane z wolnym tempem z powodu powolnego uruchamiania protokołu TCP.

Domyślna minimalna szybkość to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.

Minimalna stawka ma również zastosowanie do odpowiedzi. Kod do ustawienia limitu żądań i limitu odpowiedzi jest taki sam z wyjątkiem właściwości RequestBody lub Response w nazwach właściwości i interfejsu.

Oto przykład, który pokazuje, jak skonfigurować minimalne stawki danych w programie 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);
});

Zastąp limity minimalnej szybkości na żądanie w oprogramowania pośredniczącego:

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

Żadna funkcja szybkości przywołyowana w poprzedniej próbce nie jest dostępna w przypadku żądań HTTP/2, ponieważ modyfikowanie limitów szybkości dla 1 żądania nie jest obsługiwane w przypadku protokołu HTTP/2 ze względu na obsługę protokołu HttpContext.Features multipleksowania żądań. Limity szybkości dla całego serwera skonfigurowane za pośrednictwem nadal mają zastosowanie zarówno do KestrelServerOptions.Limits połączeń HTTP/1.x, jak i HTTP/2.

Limit czasu nagłówków żądań

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez który serwer spędza na otrzymywaniu nagłówków żądań. Wartość domyślna to 30 sekund.

.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łączenie

Http2.MaxStreamsPerConnection ogranicza liczbę współbieżnych strumieni żądań na połączenie HTTP/2. Nadmiarowe strumienie są odrzucane.

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

Wartość domyślna to 100.

Rozmiar tabeli nagłówka

Dekoder HPACK dekompresuje nagłówki HTTP dla połączeń HTTP/2. Http2.HeaderTableSize ogranicza rozmiar tabeli kompresji nagłówka używanej przez dekoder HPACK. Wartość jest dostarczana w oktetach i musi być większa od zera (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.

Maksymalny rozmiar ramki

Http2.MaxFrameSize wskazuje maksymalny rozmiar ładunku ramki połączenia HTTP/2 do odbierania. Wartość jest dostarczana w oktetach i musi być w okresie od 2^14 (16 384) do 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).

Maksymalny rozmiar nagłówka żądania

Http2.MaxRequestHeaderFieldSize wskazuje maksymalny dozwolony rozmiar w oktetach wartości nagłówka żądania. Ten limit dotyczy zarówno nazwy, jak i wartości w ich skompresowanych i nieskompresowanych reprezentacjach. Wartość musi być większa od zera (0).

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

Wartość domyślna to 8192.

Początkowy rozmiar okna połączenia

Http2.InitialConnectionWindowSize wskazuje maksymalną ilość danych treści żądania w bajtach buforów serwera jednocześnie zagregowanych dla wszystkich żądań (strumieni) na połączenie. Żądania są również ograniczone przez Http2.InitialStreamWindowSize . Wartość musi być większa lub równa 65 535 i mniejsza niż 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).

Początkowy rozmiar okna strumienia

Http2.InitialStreamWindowSize wskazuje maksymalną ilość danych treści żądania w bajtach buforów serwera jednocześnie na żądanie (strumień). Żądania są również ograniczone przez Http2.InitialStreamWindowSize . Wartość musi być większa lub równa 65 535 i mniejsza niż 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).

Synchroniczne operacje we/wy

AllowSynchronousIO określa, czy synchroniczne we/wy są dozwolone dla żądania i odpowiedzi. Wartość domyślna to true .

Ostrzeżenie

Duża liczba blokujących synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada. Włącz tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.

Poniższy przykład umożliwia synchroniczne we/wy:

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

Aby uzyskać informacje o innych Kestrel opcjach i limitach, zobacz:

Konfiguracja punktu końcowego

Domyślnie program ASP.NET Core z:

  • http://localhost:5000
  • https://localhost:5001 (jeśli jest obecny lokalny certyfikat dewelopera)

Określ adresy URL przy użyciu:

  • ASPNETCORE_URLS zmienna środowiskowa.
  • --urls argument wiersza polecenia.
  • urls klucz konfiguracji hosta.
  • UseUrls metoda rozszerzenia.

Wartością zapewnianą przy użyciu tych metod może być co najmniej jeden punkt końcowy HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).

Aby uzyskać więcej informacji na temat tych metod, zobacz Server URLs and Override configuration (Adresy URL serwera i przesłanianie konfiguracji).

Zostanie utworzony certyfikat dewelopera:

Niektóre przeglądarki wymagają udzielenia jawnego uprawnienia do zaufania lokalnemu certyfikatowi dewelopera.

Project konfigurują aplikacje do domyślnego uruchamiania przy użyciu protokołu HTTPS i obsługują przekierowywanie HTTPS oraz usługi HSTS.

Wywołaj Listen wywołanie metody lub , aby skonfigurować ListenUnixSocket KestrelServerOptions prefiksy adresów URL i porty dla elementu Kestrel .

UseUrls, argument wiersza polecenia, klucz konfiguracji hosta i zmienna środowiskowa również działają, ale mają ograniczenia zanotowe w dalszej części tej sekcji (domyślny certyfikat musi być dostępny dla konfiguracji punktu --urls urls ASPNETCORE_URLS końcowego HTTPS).

KestrelServerOptions Konfiguracji:

ConfigureEndpointDefaults(Akcja <ListenOptions> )

Określa konfigurację do Action uruchomienia dla każdego określonego punktu końcowego. Wywołanie ConfigureEndpointDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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 będą mieć zastosowanych wartości domyślnych.

ConfigureHttpsDefaults(Akcja <HttpsConnectionAdapterOptions> )

Określa konfigurację do Action uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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 będą mieć zastosowanych wartości domyślnych.

Configure(IConfiguration)

Tworzy modułu ładującego konfiguracji do Kestrel konfigurowania, który przyjmuje IConfiguration jako dane wejściowe. Konfiguracja musi być w zakresie sekcji konfiguracji dla Kestrel programu .

ListenOptions.UseHttps

Skonfiguruj Kestrel do używania protokołu HTTPS.

ListenOptions.UseHttps Rozszerzenia:

  • UseHttps: skonfiguruj Kestrel do używania protokołu HTTPS z certyfikatem domyślnym. Zgłasza wyjątek, jeśli nie skonfigurowano certyfikatu domyślnego.
  • 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 Parametry:

  • filename to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
  • configureOptionsto element Action do konfigurowania . HttpsConnectionAdapterOptions Zwraca wartość ListenOptions .
  • storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
  • subject to nazwa podmiotu certyfikatu.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
  • location to lokalizacja magazynu, z których ma być ładowany certyfikat.
  • serverCertificate to certyfikat X.509.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS. Należy podać co najmniej certyfikat domyślny.

Obsługiwane konfiguracje opisane poniżej:

  • Brak konfiguracji
  • Zastępowanie domyślnego certyfikatu z konfiguracji
  • Zmienianie wartości domyślnych w kodzie

Brak konfiguracji

Kestrel Nasłuchuje http://localhost:5000 na i https://localhost:5001 (jeśli jest dostępny domyślny certyfikat).

Zastępowanie domyślnego certyfikatu z konfiguracji

CreateDefaultBuilder domyślnie Configure(context.Configuration.GetSection("Kestrel")) wywołuje usługę w celu załadowania Kestrel konfiguracji. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel . Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

W poniższym appsettings.json przykładzie:

  • Ustaw wartość AllowInvalid na , aby zezwolić na używanie nieprawidłowych certyfikatów (na przykład true certyfikatów z podpisem własnym).
  • Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie), powraca do certyfikatu zdefiniowanego w obszarze Certyfikat domyślny lub certyfikat > dewelopera.
{
  "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 używania ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów. Na przykład domyślny certyfikat certyfikatów można > określić jako:

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

Uwagi dotyczące schematu:

  • W nazwach punktów końcowych nie jest uwzględniania ich litera. Na przykład wartości HTTPS i Https są prawidłowe.
  • Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu, z tą różnicą, że jest Urls on ograniczony do pojedynczej wartości.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego Urls poziomu, a nie dodając do nich. Punkty końcowe zdefiniowane w kodzie za pośrednictwem programu kumulują się z Listen punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
  • Sekcja Certificate jest opcjonalna. Jeśli sekcja nie zostanie określona, zostaną użyte wartości domyślne Certificate zdefiniowane we wcześniejszych scenariuszach. Jeśli wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie można uruchomić.
  • Sekcja Certificate obsługuje certyfikaty Hasło – ścieżki i – Magazyn podmiotu.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, o ile nie powodują konfliktów portów.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) Metoda zwraca metodę , która może służyć do uzupełnienia skonfigurowanych ustawień KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) punktu końcowego:
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, aby kontynuować iterowanie istniejącego modułu ładującego, takiego jak ten dostarczony CreateDefaultBuilder przez .

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach metody Endpoint , aby można było odczytać ustawienia niestandardowe.
  • Wiele konfiguracji może zostać załadowanych przez wywołanie options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją. Używana jest tylko ostatnia konfiguracja, chyba że Load jest jawnie wywoływana w poprzednich wystąpieniach. Metapakiet nie jest wywołany, aby można było zastąpić jego domyślną Load sekcję konfiguracji.
  • KestrelConfigurationLoader odzwierciedla rodzinę interfejsów API z programu jako przeciążenia, więc punkty końcowe kodu i konfiguracji mogą być skonfigurowane Listen KestrelServerOptions w tym samym Endpoint miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Zmienianie wartości domyślnych w kodzie

ConfigureEndpointDefaults i mogą służyć do zmiany ustawień domyślnych dla i , w tym zastępowania certyfikatu domyślnego ConfigureHttpsDefaults ListenOptions określonego w wcześniejszym HttpsConnectionAdapterOptions scenariuszu. ConfigureEndpointDefaults i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem jakichkolwiek punktów końcowych.

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

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

Kestrel obsługa SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i tym samym porcie. Aby funkcja SNI działała, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uściśniania TLS, dzięki czemu serwer może podać prawidłowy certyfikat. Klient używa zabezpieczonego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po ugodzie TLS.

Kestrel Obsługuje SNI za pośrednictwem ServerCertificateSelector wywołania zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu.

Obsługa SNI wymaga:

  • Uruchamianie na platformie docelowej netcoreapp2.1 lub nowszej. W net461 lub nowszym wywoływane jest wywołanie zwrotne, ale jest name zawsze null . Parametr jest również znany, jeśli klient nie name null poda parametru nazwy hosta w uściślicie TLS.
  • Wszystkie witryny internetowe działają w tym samym Kestrel wystąpieniu. Kestrel Nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera 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ń

Wywołaj polecenie , aby emitować dzienniki poziomu debugowania dla komunikacji UseConnectionLogging na poziomie bajtu w połączeniu. Rejestrowanie połączeń jest przydatne w przypadku rozwiązywania problemów z komunikacją niskiego poziomu, takich jak szyfrowanie TLS i za proxy. Jeśli UseConnectionLogging zostanie umieszczony przed , UseHttps szyfrowany ruch jest rejestrowany. Jeśli UseConnectionLogging zostanie umieszczony po , UseHttps odszyfrowany ruch jest rejestrowany.

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

Wiązanie z gniazdem TCP

Metoda Listen wiąże się z gniazdem TCP, a lambda opcji zezwala na konfigurację certyfikatu X.509:

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

W przykładzie skonfigurowano protokół HTTPS dla punktu końcowego za pomocą parametru ListenOptions . Użyj tego samego interfejsu API, aby skonfigurować Kestrel inne ustawienia dla określonych punktów końcowych.

W systemie Windows certyfikaty z podpisem własnym można tworzyć przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby uzyskać nieobsługiwany przykład, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć przy użyciu programu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwać na gnieździe systemu Unix za pomocą polecenia w celu poprawy wydajności przy użyciu ListenUnixSocket systemu Nginx, jak pokazano w tym przykładzie:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
  • W pliku konkubacji Nginx ustaw server > location > proxy_pass wpis na http://unix:/tmp/{KESTREL SOCKET}:/; wartość . {KESTREL SOCKET} to nazwa gniazda dostarczonego dla ListenUnixSocket (na przykład kestrel-test.sock w poprzednim przykładzie).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład chmod go+w /tmp/kestrel-test.sock ).

Port 0

Po podano numer 0 portu, Kestrel dynamicznie wiąże się z dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port Kestrel jest faktycznie powiązany w czasie wykonywania:

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, na którym można uzyskać do aplikacji:

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

Ograniczenia

Skonfiguruj punkty końcowe przy użyciu następujących metod:

  • UseUrls
  • --urls argument wiersza polecenia
  • urls klucz konfiguracji hosta
  • ASPNETCORE_URLS zmienna środowiskowa

Te metody są przydatne do pracy z kodem na serwerach innych niż Kestrel . Należy jednak pamiętać o następujących ograniczeniach:

  • Z tymi metodami nie można używać protokołu HTTPS, chyba że w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat (na przykład przy użyciu konfiguracji lub pliku konfiguracji, jak pokazano wcześniej KestrelServerOptions w tym temacie).
  • W przypadku jednoczesnego korzystania z metod i punkty Listen UseUrls końcowe Listen przesłaniają UseUrls punkty końcowe.

Konfiguracja punktu końcowego usług IIS

W przypadku korzystania z usług IIS powiązania adresu URL dla powiązań przesłonięcia usług IIS są ustawiane za pomocą metody Listen lub UseUrls . Aby uzyskać więcej informacji, zobacz ASP.NET Core module.

ListenOptions.Protocols

Właściwość ustanawia protokoły HTTP ( ) włączone w punkcie końcowym Protocols połączenia lub na HttpProtocols serwerze. Przypisz wartość do Protocols właściwości z HttpProtocols wyli roku.

HttpProtocols wartość wyli Dozwolony protokół połączenia
Http1 Tylko PROTOKÓŁ HTTP/1.1. Może być używany z lub bez użycia TLS.
Http2 Tylko HTTP/2. Może być używany bez użycia TLS tylko wtedy, gdy klient obsługuje tryb Poprzednia wiedza.
Http1AndHttp2 HTTP/1.1 i HTTP/2. Protokół HTTP/2 wymaga połączenia TLS i negocjacji protokołu warstwy aplikacji (ALPN); W przeciwnym razie połączenie zostanie domyślnie na nawiązaniu połączenia HTTP/1.1.

Protokół domyślny to HTTP/1.1.

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

  • TLS w wersji 1.2 lub nowszej
  • Renegotiation disabled (Ponowne negocjowanie jest wyłączone)
  • Kompresja wyłączona
  • Minimalne rozmiary efemerów wymiany kluczy:
    • Krzywa wielokropka Diffie-Hellman (ECDHE) [ RFC4492: ] minimum 224 bity
    • Skończony czas Diffie-Hellman (DHE): [ TLS12 ] minimum 2048 bitów
  • Zestaw szyfrowania nie jest zablokowany

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE] z krzywą wielokropkową P-256 [ FIPS186 ] jest obsługiwana domyślnie.

Poniższy przykład zezwala na połączenia HTTP/1.1 i HTTP/2 na porcie 8000. Połączenia są zabezpieczone przez zabezpieczenia TLS przy użyciu podanego certyfikatu:

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

Opcjonalnie utwórz implementację w celu filtrowania uściślień TLS dla poszczególnych IConnectionAdapter połączeń dla określonych szyfrów:

.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 konfiguracji

CreateDefaultBuilder Domyślnie serverOptions.Configure(context.Configuration.GetSection("Kestrel")) program wywołuje usługę , aby Kestrel załadować konfigurację.

W poniższym przykładzie dla wszystkich punktów końcowych programu zostanie ustanowionych domyślny protokół połączenia appsettings.json (HTTP/1.1 i HTTP/2): Kestrel

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

Poniższy przykładowy plik konfiguracji ustanawia protokół połączenia dla określonego punktu końcowego:

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

Protokoły określone w kodzie zastępują wartości ustawione przez konfigurację.

Konfiguracja transportu Libuv

Wraz z wydaniem ASP.NET Core 2.1 transport domyślny nie jest już oparty na libuv, ale na Kestrel zarządzanych gniazdach. Jest to przełomowa zmiana w przypadku ASP.NET Core 2.0 uaktualnianych do wersji 2.1, które wywołują i zależą od jednego z UseLibuv następujących pakietów:

W przypadku projektów, które wymagają użycia biblioteki Libuv:

  • Dodaj zależność dla pakietu Microsoft.AspNetCore.Server. Kestrel . Pakiet Transport.Libuv do pliku projektu aplikacji:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Wywołaj 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 URL

W przypadku korzystania z argumentu wiersza polecenia , klucza konfiguracji hosta lub zmiennej środowiskowej prefiksy adresów URL mogą być UseUrls w dowolnym z następujących --urls urls ASPNETCORE_URLS formatów.

Prawidłowe są tylko prefiksy adresów URL PROTOKOŁU HTTP. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy UseUrls użyciu .

  • Adres IPv4 z numerem portu

    http://65.55.39.10:80/
    

    0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

  • Adres IPv6 z numerem portu

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

    [::] jest odpowiednikiem protokołu IPv6 protokołu 0.0.0.0 IPv4.

  • Nazwa hosta z numerem portu

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

    Nazwy * hostów, , i , nie są + specjalne. Wszystkie wartości, które nie są rozpoznawane jako prawidłowy adres IP lub są powiązywane ze wszystkimi adresami localhost IP IPv4 i IPv6. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core na tym samym porcie, użyj serwera HTTP.sys lub odwrotnego serwera proxy, takiego jak usługi IIS, Nginx lub Apache.

    Ostrzeżenie

    Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego z nagłówkami przekazywania.

  • Nazwa localhost hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

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

    Gdy jest określony, próbuje powiązać z interfejsami sprzężenia zwrotnego localhost Kestrel IPv4 i IPv6. Jeśli żądany port jest w użyciu przez inną usługę w obu interfejsach sprzężenia zwrotnego, Kestrel uruchomienie nie powiedzie się. Jeśli którykolwiek interfejs sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej z powodu tego, że protokół IPv6 nie jest obsługiwany), program Kestrel rejestruje ostrzeżenie.

Filtrowanie hostów

Obsługuje Kestrel konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , w dużej mierze Kestrel ignoruje nazwę hosta. Host localhost to specjalny przypadek używany do powiązania z adresami sprzężenia zwrotnego. Każdy host inny niż jawny adres IP jest wiązany ze wszystkimi publicznymi adresami IP. Host nagłówki nie są weryfikowane.

Aby obejść ten problem, użyj oprogramowania pośredniczącego filtrowania hostów. Oprogramowanie pośredniczące filtrowania hostów jest dostarczane przez pakiet Microsoft.AspNetCore.HostFiltering, który jest zawarty w metapakiecie Microsoft.AspNetCore.App (ASP.NET Core 2.1 lub 2.2). Oprogramowanie pośredniczące jest dodawane przez program CreateDefaultBuilder , który wywołuje program 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>();
}

Oprogramowanie pośredniczące filtrowania hostów jest domyślnie wyłączone. Aby włączyć oprogramowanie pośredniczące, AllowedHosts zdefiniuj klucz w appsettings.json / elementach appsettings. <EnvironmentName> . json. Wartość jest rozdzielaną średnikami listą nazw hostów bez numerów portów:

appsettings.json:

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

Uwaga

Oprogramowanie pośredniczące Przekazane nagłówki ma również AllowedHosts opcję . Oprogramowanie pośredniczące nagłówków przekazywania i oprogramowanie pośredniczące filtrowania hostów mają podobne funkcje w różnych scenariuszach. Ustawienie z oprogramowaniem pośredniczącym przekazane nagłówki jest odpowiednie, gdy nagłówek nie jest zachowywany podczas przekazywania żądań za pomocą zwrotnego serwera AllowedHosts Host proxy lub usługi równoważenia obciążenia. Ustawienie oprogramowania pośredniczącego filtrowania hostów jest odpowiednie, gdy jest używane jako publiczny serwer brzegowy lub gdy AllowedHosts Kestrel nagłówek jest bezpośrednio Host przesyłany dalej.

Aby uzyskać więcej informacji na temat oprogramowania pośredniczącego z nagłówkami przekazywania, zobacz Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .

Opróżnianie żądań HTTP/1.1

Otwieranie połączeń HTTP jest czasochłonne. W przypadku protokołu HTTPS jest on również intensywnie obciążany zasobami. W związku Kestrel z tym program próbuje ponownie użyć połączeń dla protokołu HTTP/1.1. Treść żądania musi być w pełni wykorzystana, aby umożliwić ponowne użycie połączenia. Aplikacja nie zawsze zużywa treść żądania, na przykład żądania, w których serwer zwraca przekierowanie lub odpowiedź POST 404. W przypadku POST -redirect:

  • Klient mógł już wysłać część POST danych.
  • Serwer zapisuje odpowiedź 301.
  • Nie można użyć połączenia dla nowego żądania, dopóki dane z poprzedniej treści żądania POST nie zostaną w pełni odczytane.
  • Kestrel próbuje opróżnić treść żądania. Opróżnianie treści żądania oznacza odczytywanie i odrzucanie danych bez ich przetwarzania.

Proces opróżniania umożliwia przechodzenie między zezwoleniem na ponowne użycie połączenia a czasem, który zajmuje opróżnienie pozostałych danych:

  • Opróżnianie ma limit czasu 5 sekund, którego nie można skonfigurować.
  • Jeśli wszystkie dane określone przez nagłówek lub nie zostały odczytane przed limitem Content-Length Transfer-Encoding czasu, połączenie zostanie zamknięte.

Czasami możesz chcieć zakończyć żądanie natychmiast, przed lub po napisanie odpowiedzi. Na przykład klienci mogą mieć restrykcyjne limity danych, więc ograniczenie przekazanych danych może być priorytetem. W takich przypadkach, aby zakończyć żądanie, wywołaj httpContext.Abort z kontrolera, Razor strony lub oprogramowania pośredniczącego.

Istnieją zastrzeżenia do wywoływania Abort funkcji :

  • Tworzenie nowych połączeń może być powolne i kosztowne.
  • Nie ma gwarancji, że klient odczytał odpowiedź przed zamknięciem połączenia.
  • Wywoływanie Abort powinno być rzadkie i zarezerwowane w przypadku poważnych błędów, a nie typowych błędów.
    • Wywołaj Abort tylko wtedy, gdy trzeba rozwiązać określony problem. Na przykład wywołaj wywołanie , jeśli złośliwi klienci próbują uzyskać dane lub gdy w kodzie klienta znajduje się usterka, która Abort powoduje duże lub wiele POST żądań.
    • Nie wywołuj typowych sytuacji błędów, takich Abort jak HTTP 404 (Nie znaleziono).

Wywołanie httpResponse.CompleteAsync przed wywołaniem zapewnia, że Abort serwer zakończył zapisywanie odpowiedzi. Jednak zachowanie klienta nie jest przewidywalne i może nie odczytać odpowiedzi przed przerwaniem połączenia.

Ten proces różni się w przypadku protokołu HTTP/2, ponieważ protokół obsługuje przerywanie strumieni poszczególnych żądań bez zamykania połączenia. Limit czasu opróżnienia pięciu sekund nie ma zastosowania. Jeśli po zakończeniu odpowiedzi istnieją nieprzeczytane dane treści żądania, serwer wysyła ramkę HTTP/2 RST. Dodatkowe ramki danych treści żądania są ignorowane.

Jeśli to możliwe, lepiej jest, aby klienci używali nagłówka żądania Expect: 100-continue i czekali na odpowiedź serwera przed rozpoczęciem wysyłania treści żądania. Daje to klientowi możliwość zbadania odpowiedzi i przerwania przed wysłaniem niepotrzebnych danych.

Dodatkowe zasoby

Kestrelto międzyplatformowy serwer sieci Web dla ASP.NET Core. Kestrelto serwer internetowy, który jest domyślnie uwzględniony w szablonach ASP.NET Core projektu.

Kestrel obsługuje następujące scenariusze:

Kestrel Program jest obsługiwany na wszystkich platformach i wersjach obsługiwanych przez platformę .NET Core.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Kiedy używać Kestrel zwrotnego serwera proxy

KestrelMoże być używany samodzielnie lub z odwrotnym serwerem proxy, takim jak Internet Information Services (IIS), Nginxlub Apache. Zwrotny serwer proxy odbiera żądania HTTP z sieci i przekazuje je do usługi Kestrel .

Kestrel używany jako brzegowy (internetowy) serwer internetowy:

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

Kestrel używane w konfiguracji zwrotnego serwera proxy:

Kestrel komunikuje się pośrednio z Internetem za pośrednictwem zwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache

Konfiguracja z odwrotnym serwerem proxy lub bez niego jest obsługiwaną konfiguracją hostingu.

Kestrel używany jako serwer brzegowy bez zwrotnego serwera proxy nie obsługuje współużytkowania tego samego adresu IP i portu między wieloma procesami. Gdy Kestrel program jest skonfigurowany do nasłuchiwać na porcie, obsługuje cały ruch dla tego portu niezależnie od Kestrel Host nagłówków żądań. Zwrotny serwer proxy, który może udostępniać porty, ma możliwość przekazywania żądań do usługi Kestrel na unikatowy adres IP i port.

Nawet jeśli zwrotny serwer proxy nie jest wymagany, dobrym wyborem może być użycie zwrotnego serwera proxy.

Zwrotny serwer proxy:

  • Może ograniczyć dostępny publiczny obszar powierzchni aplikacji, które hostuje.
  • Zapewnia dodatkową warstwę konfiguracji i ochrony.
  • Może lepiej integrować się z istniejącą infrastrukturą.
  • Uproszczenie równoważenia obciążenia i konfiguracji bezpiecznej komunikacji (HTTPS). Tylko odwrotny serwer proxy wymaga certyfikatu X.509, a ten serwer może komunikować się z serwerami aplikacji w sieci wewnętrznej przy użyciu zwykłego protokołu HTTP.

Ostrzeżenie

Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego z nagłówkami przekazywania.

Jak używać w Kestrel ASP.NET Core aplikacji

Microsoft.AspNetCore.Server. Kestrel pakiet jest zawarty w Microsoft.AspNetCore.App metapakiecie.

ASP.NET Core szablonów projektów Kestrel są domyślnie używać. W pliku Program.cs kod szablonu wywołuje CreateDefaultBuilder , który wywołuje w UseKestrel tle.

Aby zapewnić dodatkową konfigurację po wywołaniu CreateDefaultBuilder funkcji , wywołaj element UseKestrel :

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

Aby uzyskać więcej informacji CreateDefaultBuilder na temat i budowania hosta, zobacz sekcję Konfigurowanie hosta w programie ASP.NET Core Web Host .

Kestrel Opcje

Serwer Kestrel internetowy ma opcje konfiguracji ograniczeń, które są szczególnie przydatne we wdrożeniach dostępnych z Internetu.

Ustaw ograniczenia właściwości Limits klasy KestrelServerOptions . Właściwość Limits zawiera wystąpienie klasy KestrelServerLimits .

W poniższych przykładach jest używana przestrzeń Microsoft.AspNetCore.Server.Kestrel.Core nazw :

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel Opcje , które zostały skonfigurowane w kodzie C# w poniższych przykładach, można również ustawić przy użyciu dostawcy konfiguracji. Na przykład dostawca konfiguracji plików może załadować Kestrel konfigurację z elementu appsettings.json lub appsettings.{ Plik Environment}.json:

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

Użyj jednej z następujących metod:

  • Skonfiguruj Kestrel w programie Startup.ConfigureServices :

    1. Wstrzyknąć IConfiguration wystąpienie klasy do klasy Startup . W poniższym przykładzie przyjęto założenie, że wstrzyknięta konfiguracja jest przypisana do Configuration właściwości .

    2. W Startup.ConfigureServices pliku Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

      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 budowania hosta:

    W pliku Program.cs Kestrel załaduj sekcję konfiguracji do Kestrel konfiguracji programu :

    // 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 metody działają z dowolnym dostawcą konfiguracji.

Limit czasu utrzymania aktywności

KeepAliveTimeout

Pobiera lub ustawia limit czasu keep-alive. Wartość domyślna to 2 minuty.

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

Maksymalna liczba połączeń klienta

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maksymalną liczbę współbieżnych otwartych połączeń TCP można ustawić dla całej aplikacji przy użyciu następującego kodu:

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 protokołu WebSockets). Po uaktualnieniu połączenia nie jest ono wliczane do MaxConcurrentConnections limitu.

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).

Maksymalny rozmiar treści żądania

MaxRequestBodySize

Domyślny maksymalny rozmiar treści żądania to 30 000 000 bajtów, czyli około 28,6 MB.

Zalecaną metodą przesłonięcia limitu w ASP.NET Core MVC jest użycie RequestSizeLimitAttribute atrybutu w metodzie akcji:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Oto przykład, który pokazuje, jak skonfigurować ograniczenie dla aplikacji dla każdego żądania:

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

Zastąp ustawienie dla określonego żądania w oprogramowania pośredniczącego:

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

Jeśli aplikacja skonfiguruje limit w żądaniu po tym, jak aplikacja zaczęła odczytywać żądanie, zgłaszany jest wyjątek. Istnieje właściwość, która wskazuje, czy właściwość jest w stanie tylko do odczytu, co oznacza, że jest za opóźniona, IsReadOnly MaxRequestBodySize aby skonfigurować limit.

Gdy aplikacja jest poza procesem w module ASP.NET Core,limit rozmiaru treści żądania jest wyłączony, ponieważ usługi IIS już Kestrel ustawiają limit.

Minimalna szybkość danych treści żądania

MinRequestBodyDataRate MinResponseDataRate

Kestrel Sprawdza co sekundę, czy dane docierają z określoną szybkością w bajtach na sekundę. Jeśli szybkość spadnie poniżej wartości minimalnej, zostanie upuszczany czas połączenia. Okres prolongaty to czas, przez który klient może zwiększyć szybkość wysyłania do minimum. W tym czasie ta szybkość nie jest Kestrel sprawdzana. Okres prolongaty pomaga uniknąć porzucania połączeń, które początkowo wysyłają dane z wolnym tempem z powodu powolnego uruchamiania protokołu TCP.

Domyślna minimalna szybkość to 240 bajtów na sekundę z 5-sekundowym okresem prolongaty.

Minimalna stawka ma również zastosowanie do odpowiedzi. Kod do ustawienia limitu żądań i limitu odpowiedzi jest taki sam z wyjątkiem właściwości RequestBody lub Response w nazwach właściwości i interfejsu.

Oto przykład, który pokazuje, jak skonfigurować minimalne stawki danych w programie 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ń

RequestHeadersTimeout

Pobiera lub ustawia maksymalny czas, przez który serwer spędza na otrzymywaniu nagłówków żądań. Wartość domyślna to 30 sekund.

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

Synchroniczne operacje we/wy

AllowSynchronousIO określa, czy synchroniczne we/wy są dozwolone dla żądania i odpowiedzi. Wartość domyślna to true .

Ostrzeżenie

Duża liczba blokujących synchronicznych operacji we/wy może prowadzić do zablokowania puli wątków, co sprawia, że aplikacja nie odpowiada. Włącz tylko AllowSynchronousIO w przypadku korzystania z biblioteki, która nie obsługuje asynchronicznych operacji we/wy.

Poniższy przykład wyłącza synchroniczne we/wy:

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

Aby uzyskać informacje o innych Kestrel opcjach i limitach, zobacz:

Konfiguracja punktu końcowego

Domyślnie program ASP.NET Core z:

  • http://localhost:5000
  • https://localhost:5001 (jeśli jest obecny lokalny certyfikat dewelopera)

Określ adresy URL przy użyciu:

  • ASPNETCORE_URLS zmienna środowiskowa.
  • --urls argument wiersza polecenia.
  • urls klucz konfiguracji hosta.
  • UseUrls metoda rozszerzenia.

Wartością zapewnianą przy użyciu tych metod może być co najmniej jeden punkt końcowy HTTP i HTTPS (HTTPS, jeśli jest dostępny domyślny certyfikat). Skonfiguruj wartość jako listę rozdzieloną średnikami (na przykład "Urls": "http://localhost:8000;http://localhost:8001" ).

Aby uzyskać więcej informacji na temat tych metod, zobacz Server URLs and Override configuration (Adresy URL serwera i przesłanianie konfiguracji).

Zostanie utworzony certyfikat dewelopera:

Niektóre przeglądarki wymagają udzielenia jawnego uprawnienia do zaufania lokalnemu certyfikatowi dewelopera.

Project konfigurują aplikacje do domyślnego uruchamiania przy użyciu protokołu HTTPS i obsługują przekierowywanie HTTPS oraz usługi HSTS.

Wywołaj Listen wywołanie metody lub , aby skonfigurować ListenUnixSocket KestrelServerOptions prefiksy adresów URL i porty dla elementu Kestrel .

UseUrls, argument wiersza polecenia, klucz konfiguracji hosta i zmienna środowiskowa również działają, ale mają ograniczenia zanotowe w dalszej części tej sekcji (domyślny certyfikat musi być dostępny dla konfiguracji punktu --urls urls ASPNETCORE_URLS końcowego HTTPS).

KestrelServerOptions Konfiguracji:

ConfigureEndpointDefaults(Akcja <ListenOptions> )

Określa konfigurację do Action uruchomienia dla każdego określonego punktu końcowego. Wywołanie ConfigureEndpointDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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 będą mieć zastosowanych wartości domyślnych.

ConfigureHttpsDefaults(Akcja <HttpsConnectionAdapterOptions> )

Określa konfigurację do Action uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wielokrotnie zastępuje poprzednie Action z ostatniej Action określonej.

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 będą mieć zastosowanych wartości domyślnych.

Configure(IConfiguration)

Tworzy modułu ładującego konfiguracji do Kestrel konfigurowania, który przyjmuje IConfiguration jako dane wejściowe. Konfiguracja musi być w zakresie sekcji konfiguracji dla Kestrel programu .

ListenOptions.UseHttps

Skonfiguruj Kestrel do używania protokołu HTTPS.

ListenOptions.UseHttps Rozszerzenia:

  • UseHttps: skonfiguruj Kestrel do używania protokołu HTTPS z certyfikatem domyślnym. Zgłasza wyjątek, jeśli nie skonfigurowano certyfikatu domyślnego.
  • 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 Parametry:

  • filename to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
  • password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
  • configureOptionsto element Action do konfigurowania . HttpsConnectionAdapterOptions Zwraca wartość ListenOptions .
  • storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
  • subject to nazwa podmiotu certyfikatu.
  • allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
  • location to lokalizacja magazynu, z których ma być ładowany certyfikat.
  • serverCertificate to certyfikat X.509.

W środowisku produkcyjnym należy jawnie skonfigurować protokół HTTPS. Należy podać co najmniej certyfikat domyślny.

Obsługiwane konfiguracje opisane poniżej:

  • Brak konfiguracji
  • Zastępowanie domyślnego certyfikatu z konfiguracji
  • Zmienianie wartości domyślnych w kodzie

Brak konfiguracji

Kestrel Nasłuchuje http://localhost:5000 na i https://localhost:5001 (jeśli jest dostępny domyślny certyfikat).

Zastępowanie domyślnego certyfikatu z konfiguracji

CreateDefaultBuilder Domyślnie Configure(context.Configuration.GetSection("Kestrel")) program wywołuje usługę , aby Kestrel załadować konfigurację. Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel . Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

W poniższym appsettings.json przykładzie:

  • Ustaw wartość AllowInvalid na , aby zezwolić na używanie nieprawidłowych certyfikatów (na przykład true certyfikatów z podpisem własnym).
  • Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie), powraca do certyfikatu zdefiniowanego w obszarze Certyfikat domyślny lub certyfikat > deweloperskim.
{
  "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 używania ścieżki i hasła dla dowolnego węzła certyfikatu jest określenie certyfikatu przy użyciu pól magazynu certyfikatów. Na przykład domyślny certyfikat certyfikatów można > określić jako:

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

Uwagi dotyczące schematu:

  • W nazwach punktów końcowych nie jest uwzględniania ich litera. Na przykład i HTTPS Https są prawidłowe.
  • Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu z tą różnicą, że jest ograniczony Urls do pojedynczej wartości.
  • Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego Urls poziomu, zamiast dodawać do nich. Punkty końcowe zdefiniowane w kodzie za Listen pośrednictwem programu kumulują się z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
  • Sekcja Certificate jest opcjonalna. Jeśli sekcja nie zostanie określona, zostaną użyte wartości domyślne Certificate zdefiniowane we wcześniejszych scenariuszach. Jeśli wartości domyślne nie są dostępne, serwer zgłasza wyjątek i nie można uruchomić.
  • Sekcja Certificate obsługuje certyfikaty Hasło – ścieżki i – Magazyn podmiotu.
  • W ten sposób można zdefiniować dowolną liczbę punktów końcowych, o ile nie powodują konfliktów portów.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) Metoda zwraca metodę , która może służyć do uzupełnienia skonfigurowanych ustawień KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) punktu końcowego:
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, aby kontynuować iterowanie istniejącego modułu ładującego, takiego jak ten dostarczony CreateDefaultBuilder przez .

  • Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach metody Endpoint , aby można było odczytać ustawienia niestandardowe.
  • Wiele konfiguracji może zostać załadowanych przez wywołanie options.Configure(context.Configuration.GetSection("{SECTION}")) ponownie z inną sekcją. Używana jest tylko ostatnia konfiguracja, chyba że Load w poprzednich wystąpieniach jest jawnie wywoływana. Metapakiet nie jest wywołany, aby można było zastąpić jego domyślną Load sekcję konfiguracji.
  • KestrelConfigurationLoader odzwierciedla rodzinę interfejsów API z programu jako przeciążenia, więc punkty końcowe kodu i konfiguracji mogą być skonfigurowane Listen KestrelServerOptions w tym samym Endpoint miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Zmienianie wartości domyślnych w kodzie

ConfigureEndpointDefaults i mogą służyć do zmiany ustawień domyślnych dla i , w tym zastępowania certyfikatu ConfigureHttpsDefaults ListenOptions HttpsConnectionAdapterOptions domyślnego określonego w wcześniejszym scenariuszu. ConfigureEndpointDefaults i ConfigureHttpsDefaults powinny być wywoływane przed skonfigurowaniem jakichkolwiek punktów końcowych.

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

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

Kestrel obsługa SNI

Oznaczanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i tym samym porcie. Aby funkcja SNI działała, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uściśniania TLS, dzięki czemu serwer może podać prawidłowy certyfikat. Klient używa zabezpieczonego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po ugodzie TLS.

Kestrel Obsługuje SNI za pośrednictwem ServerCertificateSelector wywołania zwrotnego. Wywołanie zwrotne jest wywoływane raz dla każdego połączenia, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu.

Obsługa SNI wymaga:

  • Uruchamianie na platformie docelowej netcoreapp2.1 lub nowszej. W net461 lub nowszym wywoływane jest wywołanie zwrotne, ale jest name zawsze null . Parametr jest również znany, jeśli klient nie name null poda parametru nazwy hosta w uściślicie TLS.
  • Wszystkie witryny internetowe działają w tym samym Kestrel wystąpieniu. Kestrel nie obsługuje udostępniania adresu IP i portu w wielu wystąpieniach bez zwrotnego serwera 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ń

Wywołaj polecenie , aby emitować dzienniki poziomu debugowania dla komunikacji UseConnectionLogging na poziomie bajtów w połączeniu. Rejestrowanie połączeń jest przydatne w przypadku rozwiązywania problemów z komunikacją niskiego poziomu, takich jak szyfrowanie TLS i za proxy. Jeśli UseConnectionLogging zostanie umieszczony przed , UseHttps szyfrowany ruch jest rejestrowany. Jeśli UseConnectionLogging zostanie umieszczony po , UseHttps odszyfrowany ruch jest rejestrowany.

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

Wiązanie z gniazdem TCP

Metoda Listen wiąże się z gniazdem TCP, a lambda opcji zezwala na konfigurację certyfikatu X.509:

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

W przykładzie skonfigurowano protokół HTTPS dla punktu końcowego za pomocą parametru ListenOptions . Użyj tego samego interfejsu API, aby skonfigurować Kestrel inne ustawienia dla określonych punktów końcowych.

W systemie Windows certyfikaty z podpisem własnym można tworzyć przy użyciu polecenia cmdlet New-SelfSignedCertificate programu PowerShell. Aby uzyskać nieobsługiwany przykład, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows certyfikaty można tworzyć przy użyciu programu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwać na gnieździe systemu Unix przy użyciu systemu Nginx w celu poprawy ListenUnixSocket wydajności, jak pokazano w poniższym przykładzie:

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 konkubacji Nginx ustaw server > location > proxy_pass wpis na http://unix:/tmp/{KESTREL SOCKET}:/; wartość . {KESTREL SOCKET} to nazwa gniazda dostarczonego dla ListenUnixSocket (na przykład kestrel-test.sock w poprzednim przykładzie).
  • Upewnij się, że gniazdo jest zapisywalne przez Nginx (na przykład chmod go+w /tmp/kestrel-test.sock ).

Port 0

Po podano numer 0 portu, Kestrel dynamicznie wiąże się z dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port Kestrel jest faktycznie powiązany w czasie wykonywania:

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, na którym można uzyskać do aplikacji:

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

Ograniczenia

Skonfiguruj punkty końcowe przy użyciu następujących metod:

  • UseUrls
  • --urls argument wiersza polecenia
  • urls klucz konfiguracji hosta
  • ASPNETCORE_URLS zmienna środowiskowa

Te metody są przydatne do pracy z kodem na serwerach innych niż Kestrel . Należy jednak pamiętać o następujących ograniczeniach:

  • Z tymi metodami nie można używać protokołu HTTPS, chyba że w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat (na przykład przy użyciu konfiguracji lub pliku konfiguracji, jak pokazano wcześniej KestrelServerOptions w tym temacie).
  • W przypadku jednoczesnego korzystania z metod i punkty Listen UseUrls końcowe Listen przesłaniają UseUrls punkty końcowe.

Konfiguracja punktu końcowego usług IIS

W przypadku korzystania z usług IIS powiązania adresu URL dla powiązań przesłonięcia usług IIS są ustawiane za pomocą metody Listen lub UseUrls . Aby uzyskać więcej informacji, zobacz ASP.NET Core module.

Konfiguracja transportu Libuv

W wersji ASP.NET Core 2.1 domyślny transport nie jest już oparty na libuv, ale na Kestrel zarządzanych gniazdach. Jest to przełomowa zmiana w przypadku ASP.NET Core 2.0 uaktualnianych do wersji 2.1, które wywołują i zależą od jednego z UseLibuv następujących pakietów:

W przypadku projektów, które wymagają użycia biblioteki Libuv:

  • Dodaj zależność dla pakietu Microsoft.AspNetCore.Server. Kestrel . Pakiet Transport.Libuv do pliku projektu aplikacji:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Wywołaj 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 URL

W przypadku UseUrls korzystania z argumentu wiersza polecenia, klucza konfiguracji hosta lub zmiennej środowiskowej prefiksy adresów URL mogą być w --urls urls dowolnym z następujących ASPNETCORE_URLS formatów.

Prawidłowe są tylko prefiksy adresów URL PROTOKOŁU HTTP. Kestrel nie obsługuje protokołu HTTPS podczas konfigurowania powiązań adresów URL przy UseUrls użyciu .

  • Adres IPv4 z numerem portu

    http://65.55.39.10:80/
    

    0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

  • Adres IPv6 z numerem portu

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

    [::] jest odpowiednikiem protokołu IPv6 protokołu 0.0.0.0 IPv4.

  • Nazwa hosta z numerem portu

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

    Nazwy * hostów, , i , nie są + specjalne. Wszystko, co nie jest rozpoznawane jako prawidłowy adres IP lub wiąże się ze wszystkimi adresami localhost IP IPv4 i IPv6. Aby powiązać różne nazwy hostów z różnymi ASP.NET Core na tym samym porcie, użyj serwera HTTP.sys lub odwrotnego serwera proxy, takiego jak IIS, Nginx lub Apache.

    Ostrzeżenie

    Hosting w konfiguracji zwrotnego serwera proxy wymaga konfiguracji oprogramowania pośredniczącego z nagłówkami przekazywania.

  • Nazwa localhost hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

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

    Gdy jest określony, próbuje powiązać z interfejsami sprzężenia zwrotnego localhost Kestrel IPv4 i IPv6. Jeśli żądany port jest w użyciu przez inną usługę w obu interfejsach sprzężenia zwrotnego, Kestrel uruchomienie nie powiedzie się. Jeśli którykolwiek z interfejsów sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej nie jest obsługiwany protokół IPv6), program Kestrel rejestruje ostrzeżenie.

Filtrowanie hostów

Program Kestrel obsługuje konfigurację na podstawie prefiksów, takich jak http://example.com:5000 , ale w dużej mierze Kestrel ignoruje nazwę hosta. Host localhost to specjalny przypadek używany do powiązania z adresami sprzężenia zwrotnego. Dowolny host inny niż jawny adres IP jest wiązany ze wszystkimi publicznymi adresami IP. Host Nagłówki nie są weryfikowane.

Aby obejść ten problem, użyj oprogramowania pośredniczącego filtrowania hostów. Oprogramowanie pośredniczące filtrowania hostów jest dostarczane przez pakiet Microsoft.AspNetCore.HostFiltering, który jest zawarty w metapakiecie Microsoft.AspNetCore.App (ASP.NET Core 2.1 lub 2.2). Oprogramowanie pośredniczące jest dodawane przez program CreateDefaultBuilder , który wywołuje : 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>();
}

Oprogramowanie pośredniczące filtrowania hosta jest domyślnie wyłączone. Aby włączyć oprogramowanie pośredniczące, zdefiniuj AllowedHosts klucz w appsettings.json / elementach appsettings. <EnvironmentName> . json. Wartość jest rozdzielaną średnikami listą nazw hostów bez numerów portów:

appsettings.json:

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

Uwaga

Oprogramowanie pośredniczące Nagłówki dalej ma również AllowedHosts opcję . Oprogramowanie pośredniczące Nagłówki dalej i oprogramowanie pośredniczące filtrowania hostów mają podobne funkcje w różnych scenariuszach. Ustawienie oprogramowania pośredniczącego z nagłówkami przekazywania jest odpowiednie, gdy nagłówek nie jest zachowywany podczas przekazywania żądań za pomocą zwrotnego serwera AllowedHosts Host proxy lub usługi równoważenia obciążenia. Ustawienie oprogramowania pośredniczącego filtrowania hosta jest odpowiednie, gdy jest używane jako publiczny serwer brzegowy lub gdy AllowedHosts Kestrel nagłówek jest bezpośrednio Host przesyłany dalej.

Aby uzyskać więcej informacji na temat oprogramowania pośredniczącego nagłówków przesyłania dalej, zobacz Konfigurowanie ASP.NET Core do pracy z serwerami proxy i usługami równoważenia obciążenia .

Opróżnianie żądania HTTP/1.1

Otwieranie połączeń HTTP jest czasochłonne. W przypadku protokołu HTTPS jest on również intensywnie obciążany zasobami. W związku z tym program próbuje ponownie użyć połączeń dla Kestrel protokołu HTTP/1.1. Treść żądania musi być w pełni wykorzystana, aby umożliwić ponowne użycie połączenia. Aplikacja nie zawsze zużywa treść żądania, taką jak żądania, w których serwer zwraca przekierowanie POST lub odpowiedź 404. W przypadku POST -redirect:

  • Klient mógł już wysłać część POST danych.
  • Serwer zapisuje odpowiedź 301.
  • Nie można użyć połączenia dla nowego żądania, dopóki dane z poprzedniej treści żądania nie POST zostaną w pełni odczytane.
  • Kestrel próbuje opróżnić treść żądania. Opróżnianie treści żądania oznacza odczytywanie i odrzucanie danych bez ich przetwarzania.

Proces opróżniania umożliwia przechodzenie między zezwoleniem na ponowne użycie połączenia a czasem, który zajmuje opróżnienie pozostałych danych:

  • Opróżnianie ma limit czasu 5 sekund, którego nie można skonfigurować.
  • Jeśli wszystkie dane określone przez nagłówek lub nie zostały odczytane przed limitem Content-Length Transfer-Encoding czasu, połączenie zostanie zamknięte.

Czasami możesz chcieć zakończyć żądanie natychmiast, przed lub po napisanie odpowiedzi. Na przykład klienci mogą mieć restrykcyjne limity danych, więc ograniczenie przekazanych danych może być priorytetem. W takich przypadkach, aby zakończyć żądanie, wywołaj httpContext.Abort z kontrolera, strony Razor lub oprogramowania pośredniczącego.

Istnieją zastrzeżenia do wywoływania Abort funkcji :

  • Tworzenie nowych połączeń może być powolne i kosztowne.
  • Nie ma gwarancji, że klient odczytał odpowiedź przed zamknięciem połączenia.
  • Wywoływanie Abort powinno być rzadkie i zarezerwowane w przypadku poważnych błędów, a nie typowych błędów.
    • Wywołaj Abort tylko wtedy, gdy trzeba rozwiązać określony problem. Na przykład wywołaj wywołanie , jeśli złośliwi klienci próbują uzyskać dane lub gdy w kodzie klienta znajduje się usterka, która Abort powoduje duże lub wiele POST żądań.
    • Nie wywołuj typowych sytuacji błędów, takich Abort jak HTTP 404 (Nie znaleziono).

Wywołanie httpResponse.CompleteAsync przed wywołaniem zapewnia, że Abort serwer zakończył zapisywanie odpowiedzi. Jednak zachowanie klienta nie jest przewidywalne i może nie odczytać odpowiedzi przed przerwaniem połączenia.

Ten proces różni się w przypadku protokołu HTTP/2, ponieważ protokół obsługuje przerywanie poszczególnych strumieni żądań bez zamykania połączenia. Limit czasu opróżnienia pięciu sekund nie ma zastosowania. Jeśli po zakończeniu odpowiedzi istnieją nieprzeczytane dane treści żądania, serwer wysyła ramkę HTTP/2 RST. Dodatkowe ramki danych treści żądania są ignorowane.

Jeśli to możliwe, lepiej jest, aby klienci korzystali z nagłówka żądania Expect: 100-continue i czekali, aż serwer odpowie przed rozpoczęciem wysyłania treści żądania. Daje to klientowi możliwość zbadania odpowiedzi i przerwania jej przed wysłaniem niepotrzebnych danych.

Dodatkowe zasoby