Kestrel webový server v ASP.NET Core

  • Článek

Tom Dykstra, Chris Ross a Stephen Halter

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel je doporučený server pro ASP.NET Core a ve výchozím nastavení je nakonfigurovaný v šablonách projektu ASP.NET Core.

KestrelMezi funkce patří:

  • Multiplatformní:Kestrel je multiplatformní webový server, který běží ve Windows, Linuxu a macOS.
  • Vysoký výkon:Kestrel je optimalizovaný pro efektivní zpracování velkého počtu souběžných připojení.
  • Lightweight: Optimalizované pro spouštění v prostředích s omezenými prostředky, jako jsou kontejnery a hraniční zařízení.
  • Posílení zabezpečení:Kestrel podporuje protokol HTTPS a je posílen proti ohrožením zabezpečení webového serveru.
  • Podpora širokého protokolu:Kestrel podporuje běžné webové protokoly, včetně:
  • Integrace s ASP.NET Core: Bezproblémová integrace s jinými komponentami ASP.NET Core, jako je kanál middlewaru, injektáž závislostí a konfigurační systém.
  • Flexibilní úlohy: Kestrel podporuje mnoho úloh:
    • ASP.NET aplikační architektury, jako jsou minimální rozhraní API, MVC, Razor stránky, SignalR, , Blazora gRPC.
    • Vytvoření reverzního proxy serveru pomocí YARP
  • Rozšiřitelnost: Přizpůsobení Kestrel prostřednictvím konfigurace, middlewaru a vlastních přenosů
  • Diagnostika výkonu:Kestrel Poskytuje integrované funkce diagnostiky výkonu, jako jsou protokolování a metriky.

Začínáme

ASP.NET šablony projektů Core se ve výchozím nastavení používají Kestrel , pokud nejsou hostované ve službě IIS. V následující šabloně vygenerovaná Program.csWebApplication.CreateBuilder metoda interně voláUseKestrel:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Další informace o konfiguraci WebApplication a WebApplicationBuildernaleznete v tématu Minimální referenční informace k rozhraním API.

Volitelné klientské certifikáty

Informace o aplikacích, které musí chránit podmnožinu aplikace pomocí certifikátu, najdete v části Volitelné klientské certifikáty.

Chování s připojeným ladicím programem

Při připojení ladicího programu k Kestrel procesu se nevynucují následující časové limity a limity rychlosti:

Další prostředky

Poznámka

Od ASP.NET Core 5.0 Kestrelje přenos libuv zastaralý. Přenos libuv nepřijímá aktualizace pro podporu nových platforem operačního systému, jako je Windows ARM64, a bude odebrán v budoucí verzi. Odeberte všechna volání zastaralé UseLibuv metody a místo toho použijte Kestrelvýchozí přenos soketů.

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel je webový server, který je zahrnutý a povolený ve výchozím nastavení v šablonách projektu ASP.NET Core.

Kestrel podporuje následující scénáře:

  • HTTPS
  • HTTP/2 (s výjimkou macOS†)
  • Neprůžný upgrade použitý k povolení webSocketů
  • Unixové sokety pro vysoký výkon za Nginx

†HTTP/2 se v macOS bude podporovat v budoucí verzi.

Kestrel podporuje se na všech platformách a verzích, které .NET Core podporuje.

Začínáme

ASP.NET šablony projektů Core se ve výchozím nastavení používají Kestrel , pokud nejsou hostované ve službě IIS. V následující šabloně vygenerovaná Program.csWebApplication.CreateBuilder metoda interně voláUseKestrel:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Další informace o konfiguraci WebApplication a WebApplicationBuildernaleznete v tématu Minimální referenční informace k rozhraním API.

Volitelné klientské certifikáty

Informace o aplikacích, které musí chránit podmnožinu aplikace pomocí certifikátu, najdete v části Volitelné klientské certifikáty.

Chování s připojeným ladicím programem

Při připojení ladicího programu k Kestrel procesu se nevynucují následující časové limity a limity rychlosti:

Další prostředky

Poznámka

Od ASP.NET Core 5.0 Kestrelje přenos libuv zastaralý. Přenos libuv nepřijímá aktualizace pro podporu nových platforem operačního systému, jako je Windows ARM64, a bude odebrán v budoucí verzi. Odeberte všechna volání zastaralé UseLibuv metody a místo toho použijte Kestrelvýchozí přenos soketů.

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel je webový server, který je zahrnutý a povolený ve výchozím nastavení v šablonách projektu ASP.NET Core.

Kestrel podporuje následující scénáře:

  • HTTPS
  • HTTP/2 (s výjimkou macOS†)
  • Neprůžný upgrade použitý k povolení webSocketů
  • Unixové sokety pro vysoký výkon za Nginx

†HTTP/2 se v macOS bude podporovat v budoucí verzi.

Kestrel podporuje se na všech platformách a verzích, které .NET Core podporuje.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Začínáme

ASP.NET šablony projektů Core se ve výchozím nastavení používají Kestrel , pokud nejsou hostované ve službě IIS. V Program.cs, ConfigureWebHostDefaults metoda volání 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>();
        });

Další informace o vytváření hostitele najdete v části Nastavení hostitele a výchozího nastavení tvůrce v rozhraní .NET Generic Host v ASP.NET Core.

Volitelné klientské certifikáty

Informace o aplikacích, které musí chránit podmnožinu aplikace pomocí certifikátu, najdete v části Volitelné klientské certifikáty.

Další prostředky

Poznámka

Od ASP.NET Core 5.0 Kestrelje přenos libuv zastaralý. Přenos libuv nepřijímá aktualizace pro podporu nových platforem operačního systému, jako je Windows ARM64, a bude odebrán v budoucí verzi. Odeberte všechna volání zastaralé UseLibuv metody a místo toho použijte Kestrelvýchozí přenos soketů.

Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel je webový server, který je ve výchozím nastavení součástí šablon projektů ASP.NET Core.

Kestrel podporuje následující scénáře:

  • HTTPS
  • Neprůžný upgrade použitý k povolení webSocketů
  • Unixové sokety pro vysoký výkon za Nginx
  • HTTP/2 (s výjimkou macOS†)

†HTTP/2 se v macOS bude podporovat v budoucí verzi.

Kestrel podporuje se na všech platformách a verzích, které .NET Core podporuje.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Podpora HTTP/2

Http/2 je k dispozici pro aplikace ASP.NET Core, pokud jsou splněny následující základní požadavky:

  • Operační systém†
    • Windows Server 2016/Windows 10 nebo novější
    • Linux s OpenSSL 1.0.2 nebo novější (například Ubuntu 16.04 nebo novější)
  • Cílová architektura: .NET Core 2.2 nebo novější
  • Připojení k vyjednávání protokolu aplikační vrstvy (ALPN)
  • Připojení přes protokol TLS 1.2 nebo novější

†HTTP/2 se v macOS bude podporovat v budoucí verzi. –Kestrel má omezenou podporu protokolu HTTP/2 ve Windows Serveru 2012 R2 a Windows 8.1. Podpora je omezená, protože seznam podporovaných šifrovacích sad TLS dostupných v těchto operačních systémech je omezený. K zabezpečení připojení TLS může být potřeba certifikát vygenerovaný pomocí algoritmu ECDSA (Elliptic Curve Digital Signature Algorithm).

Pokud je navázáno připojení HTTP/2, HttpRequest.Protocol hlásí zprávu HTTP/2.

Od verze .NET Core 3.0 je ve výchozím nastavení povolený protokol HTTP/2. Další informace o konfiguraci najdete v Kestrel částech Možnosti a ListenOptions.Protocols .

Kdy použít Kestrel s reverzním proxy serverem

Kestrellze použít samostatně nebo s reverzním proxy serverem. Reverzní proxy server přijímá požadavky HTTP ze sítě a předává je do Kestrel. Mezi příklady reverzního proxy serveru patří:

Kestrel používá se jako hraniční (internetový) webový server:

Kestrel communicates directly with the Internet without a reverse proxy server

Kestrel používá se v konfiguraci reverzního proxy serveru:

Kestrel communicates indirectly with the Internet through a reverse proxy server, such as IIS, Nginx, or Apache

Konfigurace s reverzním proxy serverem nebo bez této konfigurace je podporovaná konfigurace hostování.

Kestrel používá se jako hraniční server bez reverzního proxy serveru nepodporuje sdílení stejné IP adresy a portu mezi několika procesy. Pokud Kestrel je nakonfigurované naslouchání na portu, Kestrel zpracovává veškerý provoz pro tento port bez ohledu na hlavičky požadavků Host . Reverzní proxy server, který může sdílet porty, má možnost předávat požadavky na Kestrel jedinečnou IP adresu a port.

I když není reverzní proxy server povinný, může být použití reverzního proxy serveru dobrou volbou.

Reverzní proxy server:

  • Může omezit vystavenou veřejnou plochu aplikací, které hostuje.
  • Poskytuje další vrstvu konfigurace a obrany.
  • Může se lépe integrovat se stávající infrastrukturou.
  • Zjednodušení vyrovnávání zatížení a konfigurace zabezpečené komunikace (HTTPS). Pouze reverzní proxy server vyžaduje certifikát X.509 a tento server může komunikovat se servery aplikace v interní síti pomocí prostého protokolu HTTP.

Upozorňující

Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci middlewaru Forwarded Headers.

Kestrel v aplikacích ASP.NET Core

ASP.NET šablony základních projektů používají Kestrel ve výchozím nastavení. V Program.cs, ConfigureWebHostDefaults metoda volání 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>();
        });

Další informace o vytváření hostitele najdete v části Nastavení hostitele a výchozího nastavení tvůrce v rozhraní .NET Generic Host v ASP.NET Core.

Pokud chcete po volání ConfigureWebHostDefaultsposkytnout další konfiguraci, použijte 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 Možnosti

Webový Kestrel server má možnosti konfigurace omezení, které jsou užitečné zejména v nasazeních s internetovým prostředím.

Nastavte omezení vlastnosti LimitsKestrelServerOptions třídy. Vlastnost Limits obsahuje instanci KestrelServerLimits třídy.

Následující příklady používají Microsoft.AspNetCore.Server.Kestrel.Core obor názvů:

using Microsoft.AspNetCore.Server.Kestrel.Core;

V příkladech uvedených dále v tomto článku Kestrel jsou možnosti nakonfigurované v kódu jazyka C#. Kestrel možnosti lze také nastavit pomocí zprostředkovatele konfigurace. Zprostředkovatel konfigurace souboru může například načíst Kestrel konfiguraci z nebo appsettings.jsonappsettings.{Environment}.json ze souboru:

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

Poznámka

KestrelServerOptionskonfigurace koncového bodu je možné konfigurovat od poskytovatelů konfigurace. Zbývající Kestrel konfigurace musí být nakonfigurovaná v kódu jazyka C#.

Použijte jeden z následujících přístupů:

  • Konfigurovat Kestrel v Startup.ConfigureServices:

    1. Vložte instanci IConfiguration do Startup třídy. Následující příklad předpokládá, že vložená konfigurace je přiřazena Configuration k vlastnosti.

    2. V Startup.ConfigureServicesčásti konfigurace načtěte Kestrel do Kestrelkonfigurace:

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

  • Konfigurace Kestrel při sestavování hostitele:

    V Program.csčásti konfigurace načtěte Kestrel do Kestrelkonfigurace:

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

Oba předchozí přístupy fungují s libovolným poskytovatelem konfigurace.

Časový limit zachování

KeepAliveTimeout

Získá nebo nastaví časový limit udržování. Výchozí hodnota je 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);
})

Maximální počet připojení klientů

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maximální počet souběžných otevřených připojení TCP lze nastavit pro celou aplikaci pomocí následujícího kódu:

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

Pro připojení upgradovaná z HTTP nebo HTTPS na jiný protokol (například v požadavku WebSockets) existuje samostatný limit. Po upgradu připojení se do limitu MaxConcurrentConnections nezapočítává.

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

Maximální počet připojení je ve výchozím nastavení neomezený (null).

Maximální velikost textu požadavku

MaxRequestBodySize

Výchozí maximální velikost těla požadavku je 30 000 000 bajtů, což je přibližně 28,6 MB.

Doporučeným přístupem k přepsání limitu v aplikaci ASP.NET Core MVC je použití atributu RequestSizeLimitAttribute pro metodu akce:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Tady je příklad, který ukazuje, jak nakonfigurovat omezení pro aplikaci na každém požadavku:

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

Přepište nastavení konkrétního požadavku v middlewaru:

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

Pokud aplikace nakonfiguruje limit požadavku poté, co aplikace začne číst požadavek, vyvolá se výjimka. IsReadOnly Existuje vlastnost, která označuje, jestli MaxRequestBodySize je vlastnost ve stavu jen pro čtení, což znamená, že je příliš pozdě na konfiguraci limitu.

Když je aplikace za modulem ASP.NET Core spuštěná,limit velikosti těla požadavku je zakázaný, Kestrelprotože služba IIS už limit nastaví.

Minimální přenosová rychlost textu požadavku

MinRequestBodyDataRate MinResponseDataRate

Kestrel kontroluje každou sekundu, pokud data přicházejí na zadanou rychlost v bajtech za sekundu. Pokud rychlost klesne pod minimum, vyprší časový limit připojení. Období odkladu je doba, po kterou Kestrel má klient zvýšit rychlost odesílání až na minimum. Během této doby se sazba nekontroluje. Období odkladu pomáhá vyhnout se vyřazení připojení, která zpočátku odesílají data pomalou rychlostí kvůli pomalému spuštění protokolu TCP.

Výchozí minimální sazba je 240 bajtů za sekundu s obdobím odkladu 5 sekund.

Minimální sazba se vztahuje také na odpověď. Kód pro nastavení limitu požadavku a limit odpovědi je stejný s výjimkou vlastností RequestBody nebo Response názvů rozhraní.

Tady je příklad, který ukazuje, jak nakonfigurovat minimální rychlost dat v 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);
})

Přepsání minimálních limitů rychlosti na požadavek v middlewaru:

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

Odkazovaný IHttpMinResponseDataRateFeature v předchozím vzorku není u požadavků HTTP/2 k dispozici HttpContext.Features , protože úprava limitů rychlosti na základě požadavku se obecně nepodporuje pro HTTP/2 kvůli podpoře protokolu pro multiplexování požadavků. IHttpMinRequestBodyDataRateFeature Stále však platí HttpContext.Features pro požadavky HTTP/2, protože limit rychlosti čtení je stále možné zakázat zcela na základě požadavku na požadavek, a to nastavením IHttpMinRequestBodyDataRateFeature.MinDataRatenull dokonce i pro požadavek HTTP/2. Pokus o přečtení IHttpMinRequestBodyDataRateFeature.MinDataRate nebo pokus o jeho nastavení na jinou hodnotu, než null způsobí NotSupportedException vyvolání požadavku HTTP/2.

Omezení rychlosti na úrovni serveru nakonfigurovaná prostřednictvím KestrelServerOptions.Limits stále platí pro připojení HTTP/1.x i HTTP/2.

Vypršení časového limitu hlavičky požadavku

RequestHeadersTimeout

Získá nebo nastaví maximální dobu, po kterou server stráví příjmem hlaviček požadavků. Výchozí hodnota je 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);
})

Maximální počet datových proudů na připojení

Http2.MaxStreamsPerConnection omezuje počet souběžných datových proudů požadavků na připojení HTTP/2. Nadbytečné proudy jsou odmítnuty.

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

Výchozí hodnota je 100.

Velikost tabulky záhlaví

Dekodér HPACK dekomprimuje hlavičky HTTP pro připojení HTTP/2. Http2.HeaderTableSize omezuje velikost tabulky komprese hlaviček, kterou dekodér HPACK používá. Hodnota je zadána v oktetech a musí být větší než nula (0).

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

Výchozí hodnota je 4096.

Maximální velikost rámce

Http2.MaxFrameSize označuje maximální povolenou velikost datové části rámce připojení HTTP/2 přijaté nebo odeslané serverem. Hodnota je zadaná v oktetech a musí být mezi 2^14 (16 384) a 2^24-1 (16 777 215).

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

Výchozí hodnota je 2^14 (16 384).

Maximální velikost hlavičky požadavku

Http2.MaxRequestHeaderFieldSize určuje maximální povolenou velikost v oktetech hodnot hlavičky požadavku. Tento limit platí pro název i hodnotu v komprimovaných i nekomprimovaných reprezentacích. Hodnota musí být větší než nula (0).

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

Výchozí hodnota je 8 192.

Počáteční velikost okna připojení

Http2.InitialConnectionWindowSize označuje maximální data textu požadavku v bajtech vyrovnávací paměti serveru najednou agregovaná napříč všemi požadavky (datovými proudy) na připojení. Požadavky jsou také omezeny Http2.InitialStreamWindowSize. Hodnota musí být větší nebo rovna 65 535 a menší než 2^31 (2 147 483 648).

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

Výchozí hodnota je 128 kB (131 072).

Počáteční velikost okna datového proudu

Http2.InitialStreamWindowSize označuje maximální data textu požadavku v bajtech vyrovnávací paměti serveru najednou na každý požadavek (datový proud). Požadavky jsou také omezeny Http2.InitialConnectionWindowSize. Hodnota musí být větší nebo rovna 65 535 a menší než 2^31 (2 147 483 648).

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

Výchozí hodnota je 96 kB (98 304).

Přívěsy

Přívěsy HTTP se podobají hlavičce HTTP, s výjimkou toho, že se odešlou po odeslání textu odpovědi. Pro SLUŽBU IIS a HTTP.sys jsou podporovány pouze přívěsy odpovědí HTTP/2.

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

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

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

V předchozím ukázkovém kódu:

  • SupportsTrailers zajišťuje, aby byly pro odpověď podporovány přívěsy.
  • DeclareTrailer přidá daný název přívěsu do hlavičky Trailer odpovědi. Deklarování přívěsů odpovědí je volitelné, ale doporučuje se. Pokud DeclareTrailer je volána, musí být před odesláním hlaviček odpovědi.
  • AppendTrailer připojí přívěs.

Reset

Resetování umožňuje serveru resetovat požadavek HTTP/2 se zadaným kódem chyby. Žádost o resetování se považuje za přerušenou.

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

Reset v předchozím příkladu kódu určuje INTERNAL_ERROR kód chyby. Další informace o kódech chyb HTTP/2 najdete v části kód chyby specifikace HTTP/2.

Synchronní vstupně-výstupní operace

AllowSynchronousIO určuje, jestli je pro požadavek a odpověď povolen synchronní vstupně-výstupní operace. Výchozí hodnota je false.

Upozorňující

Velký počet blokujících synchronní vstupně-výstupní operace může vést k hladovění fondu vláken, což způsobí, že aplikace nereaguje. Povolte AllowSynchronousIO pouze při použití knihovny, která nepodporuje asynchronní vstupně-výstupní operace.

Následující příklad umožňuje synchronní vstupně-výstupní operace:

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

Informace o dalších Kestrel možnostech a omezeních najdete tady:

Konfigurace koncového bodu

Ve výchozím nastavení ASP.NET Core vytvoří vazbu na:

  • http://localhost:5000
  • https://localhost:5001 (pokud je k dispozici místní vývojový certifikát)

Zadejte adresy URL pomocí:

  • ASPNETCORE_URLS proměnná prostředí.
  • --urls argument příkazového řádku.
  • urls konfigurační klíč hostitele.
  • UseUrls rozšiřující metoda.

Hodnota zadaná pomocí těchto přístupů může být jeden nebo více koncových bodů HTTP a HTTPS (pokud je k dispozici výchozí certifikát). Nakonfigurujte hodnotu jako seznam oddělený středníkem (například "Urls": "http://localhost:8000;http://localhost:8001").

Další informace o těchtopřístupch

Vytvoří se vývojový certifikát:

Některé prohlížeče vyžadují udělení explicitního oprávnění k důvěryhodnosti místního vývojového certifikátu.

Šablony projektů konfigurují aplikace pro spouštění na HTTPS ve výchozím nastavení a zahrnují podporu přesměrování HTTPS a HSTS.

Volání Listen nebo ListenUnixSocket metody KestrelServerOptions konfigurace předpon adres URL a portů pro Kestrel.

UseUrls--urls, argument příkazového řádku, urls konfigurační klíč hostitele a ASPNETCORE_URLS proměnná prostředí také fungují, ale mají omezení, která jsou uvedena dále v této části (pro konfiguraci koncového bodu HTTPS musí být dostupný výchozí certifikát).

KestrelServerOptions Konfigurace:

ConfigureEndpointDefaults(Action<ListenOptions>)

Určuje konfiguraci Action , která se má spustit pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults několikrát nahradí předchozí Actions posledním Action zadaným číslem.

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

Poznámka

Koncové body vytvořené voláním Listenpřed voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

KonfiguraceHttpsDefaults(Akce<Https Připojení ionAdapterOptions>)

Určuje konfiguraci Action , která se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults několikrát nahradí předchozí Actions posledním Action zadaným číslem.

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

Poznámka

Koncové body vytvořené voláním Listenpřed voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

Configure(IConfiguration)

Vytvoří zavaděč konfigurace pro nastavení Kestrel , které přebírá IConfiguration jako vstup. Konfigurace musí být vymezena na oddíl konfigurace pro Kestrel.

ListenOptions.UseHttps

Nakonfigurujte Kestrel použití PROTOKOLU HTTPS.

ListenOptions.UseHttps Rozšíření:

  • UseHttps: Nakonfigurujte Kestrel použití protokolu HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurovaný žádný výchozí certifikát.
  • 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 je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
  • password je heslo potřebné pro přístup k datům certifikátu X.509.
  • configureOptions je konfigurace ActionHttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
  • storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
  • subject je název subjektu certifikátu.
  • allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
  • location je umístění úložiště, ze které se má certifikát načíst.
  • serverCertificate je certifikát X.509.

V produkčním prostředí musí být https explicitně nakonfigurované. Musí se zadat minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

  • Bez konfigurace
  • Nahrazení výchozího certifikátu z konfigurace
  • Změna výchozích hodnot v kódu

Bez konfigurace

Kestrel naslouchá a http://localhost:5000https://localhost:5001 (pokud je k dispozici výchozí certifikát).

Nahrazení výchozího certifikátu z konfigurace

CreateDefaultBuilder ve výchozím nastavení volá Configure(context.Configuration.GetSection("Kestrel")) konfiguraci načtení Kestrel . Pro nastavení aplikace HTTPS je k dispozici Kestrelvýchozí schéma konfigurace nastavení aplikace HTTPS . Nakonfigurujte několik koncových bodů, včetně adres URL a certifikátů, které se mají použít, a to buď ze souboru na disku, nebo z úložiště certifikátů.

V následujícím appsettings.json příkladu:

  • Nastavte AllowInvalid tak, aby true povolovala použití neplatných certifikátů (například certifikátů podepsaných svým držitelem).
  • Jakýkoli koncový bod HTTPS, který neurčuje certifikát (v následujícím příkladu httpsDefaultCert), se vrátí k certifikátu definovanému ve výchozím nastavení certifikátů>nebo vývojovém certifikátu.
{
  "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>"
      }
    }
  }
}

Alternativou k použití cesty a hesla pro jakýkoli uzel certifikátu je určení certifikátu pomocí polí úložiště certifikátů. Například výchozí certifikát certifikátů>lze zadat takto:

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

Poznámky ke schématu:

  • Názvy koncových bodů nerozlišují malá a velká písmena. Jsou například HTTPSHttps platné.
  • Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu.
  • Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls , a ne přidají do nich. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
  • Oddíl Certificate je nepovinný. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v předchozích scénářích. Pokud nejsou k dispozici žádné výchozí hodnoty, server vyvolá výjimku a nepodaří se spustit.
  • Tato Certificate část podporuje certifikáty Path-Password i Subject-Store.
  • Libovolný počet koncových bodů může být definován tímto způsobem, pokud nezpůsobí konflikty portů.
  • options.Configure(context.Configuration.GetSection("{SECTION}"))KestrelConfigurationLoader vrátí metodu.Endpoint(string name, listenOptions => { }), která se dá použít k doplnění nakonfigurovaného nastavení koncového bodu:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader lze získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který CreateDefaultBuilderposkytuje .

  • Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
  • Více konfigurací může být načteno opětovným voláním options.Configure(context.Configuration.GetSection("{SECTION}")) s jinou částí. Použije se pouze poslední konfigurace, pokud Load není explicitně volána u předchozích instancí. Metabalíc nevolá Load , aby se mohl nahradit výchozí konfigurační oddíl.
  • KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptionsEndpoint přetížení, takže je možné nakonfigurovat koncové body kódu a konfigurace na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Změna výchozích hodnot v kódu

ConfigureEndpointDefaultsa ConfigureHttpsDefaults lze ho použít ke změně výchozího nastavení a HttpsConnectionAdapterOptionsListenOptions , včetně přepsání výchozího certifikátu zadaného v předchozím scénáři. ConfigureEndpointDefaults a ConfigureHttpsDefaults měly by se volat před konfigurací všech koncových bodů.

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

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

Kestrel podpora SNI

Indikaci názvu serveru (SNI) lze použít k hostování více domén na stejné IP adrese a portu. Aby rozhraní SNI fungovalo, klient odešle název hostitele pro zabezpečenou relaci na server během metody handshake protokolu TLS, aby server mohl poskytnout správný certifikát. Klient používá zařízený certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje za metodou handshake protokolu TLS.

Kestrel podporuje SNI prostřednictvím zpětného ServerCertificateSelector volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát.

Podpora SNI vyžaduje:

  • Běží v cílovém rozhraní netcoreapp2.1 nebo novějším. Při net461 nebo novějším je vyvoláno zpětné volání, ale name je vždy null. To name platí také null v případě, že klient nezadá parametr názvu hostitele v metodě handshake protokolu TLS.
  • Všechny weby běží ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.
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;
            };
        });
    });
});

protokolování Připojení

Volání UseConnectionLogging pro generování protokolů na úrovni ladění pro komunikaci na úrovni bajtů v připojení. Protokolování Připojení je užitečné při řešení problémů s komunikací nízké úrovně, například při šifrování TLS a za proxy servery. Pokud UseConnectionLogging je před umístěním UseHttps, zašifrovaný provoz se zaprotokoluje. Pokud UseConnectionLogging je umístěn po UseHttps, dešifrovaný provoz se zaprotokoluje.

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

Vytvoření vazby k soketu TCP

Metoda Listen vytvoří vazbu na soket TCP a možnost lambda umožňuje konfiguraci certifikátu 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>();
        });

Příklad nakonfiguruje HTTPS pro koncový bod s ListenOptions. Ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body použijte stejné rozhraní API.

Ve Windows je možné vytvořit certifikáty podepsané svým držitelem pomocí rutiny PowerShellu.New-SelfSignedCertificate Nepodporovaný příklad najdete v tématu UpdateIISExpressSSLForChrome.ps1.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Vytvoření vazby k soketu Unix

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • V konfiguračním souboru Nginx nastavte server>proxy_pass>locationpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
  • Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Port 0

Pokud je zadané číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit, který port Kestrel je skutečně vázaný za běhu:

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

Když je aplikace spuštěná, výstup okna konzoly označuje dynamický port, na kterém je možné aplikaci dosáhnout:

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

Omezení

Nakonfigurujte koncové body pomocí následujících přístupů:

  • UseUrls
  • --urls Argument příkazového řádku
  • urls konfigurační klíč hostitele
  • ASPNETCORE_URLS proměnná prostředí

Tyto metody jsou užitečné pro práci s kódem s jinými servery než Kestrel. Mějte však na paměti následující omezení:

  • Https se s těmito přístupy nedá použít, pokud není v konfiguraci koncového bodu HTTPS k dispozici výchozí certifikát (například použití KestrelServerOptions konfigurace nebo konfiguračního souboru, jak je znázorněno výše v tomto tématu).
  • ListenUseUrls Když se současně používají oba přístupy, Listen koncové body přepíší UseUrls koncové body.

Konfigurace koncového bodu služby IIS

Při použití služby IIS jsou vazby adresy URL pro vazby přepsání služby IIS nastaveny buď Listen nebo UseUrls. Další informace najdete v tématu modulu ASP.NET Core .

ListenOptions.Protocols

Vlastnost Protocols vytvoří protokoly HTTP (HttpProtocols) povolené v koncovém bodu připojení nebo pro server. Přiřaďte hodnotu vlastnosti Protocols z výčtu HttpProtocols .

HttpProtocols enum value povolený protokol Připojení ion
Http1 Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
Http2 Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
Http1AndHttp2 HTTP/1.1 a HTTP/2. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota každého koncového bodu je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

  • TLS verze 1.2 nebo novější
  • Opětovné vyjednávání zakázáno
  • Komprese je zakázaná
  • Minimální dočasné velikosti výměny klíčů:
    • Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
    • Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
  • Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Následující příklad umožňuje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení jsou zabezpečeny protokolem TLS pomocí dodaného certifikátu:

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

Pomocí middlewaru Připojení ion můžete filtrovat metody handshake protokolu TLS na základě jednotlivých připojení pro konkrétní šifry, pokud je to potřeba.

Následující příklad vyvolá NotSupportedException jakýkoli algoritmus šifry, který aplikace nepodporuje. Případně můžete definovat a porovnat ITlsHandshakeFeature.CipherAlgorithm se seznamem přijatelných šifrovacích sad.

U šifrovacího algoritmu CipherAlgorithmType.Null se nepoužívá žádné šifrování.

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

filtrování Připojení je možné nakonfigurovat také prostřednictvím IConnectionBuilder lambda:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě připojení:

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

Nastavení protokolu z konfigurace

CreateDefaultBuilder ve výchozím nastavení volá serverOptions.Configure(context.Configuration.GetSection("Kestrel")) konfiguraci načtení Kestrel .

Následující appsettings.json příklad vytvoří http/1.1 jako výchozí připojovací protokol pro všechny koncové body:

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

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

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

Protokoly zadané v hodnotách přepsání kódu nastavených konfigurací.

Předpony adres URL

Při použití UseUrlsargumentu --urls příkazového řádku, urls konfiguračního klíče hostitele nebo ASPNETCORE_URLS proměnné prostředí můžou být předpony adresy URL v libovolném z následujících formátů.

Platné jsou pouze předpony adresy URL HTTP. Kestrel nepodporuje HTTPS při konfiguraci vazeb adres URL pomocí UseUrls.

  • Adresa IPv4 s číslem portu

    http://65.55.39.10:80/

    0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.

  • Adresa IPv6 s číslem portu

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

    [::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.

  • Název hostitele s číslem portu

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

    Názvy hostitelů a *+, nejsou zvláštní. Nic se nerozpoznalo jako platná IP adresa nebo localhost vazba na všechny IP adresy IPv4 a IPv6. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server, jako je IIS, Nginx nebo Apache.

    Upozorňující

    Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci middlewaru Forwarded Headers.

  • Název hostitele localhost s číslem portu nebo IP adresou zpětné smyčky s číslem portu

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

    Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

Filtrování hostitele

Přestože Kestrel podporuje konfiguraci založenou na předponách, jako http://example.com:5000je , Kestrel z velké části ignoruje název hostitele. Hostitel localhost je speciální případ používaný pro vazbu na adresy zpětné smyčky. Jakýkoli jiný hostitel než explicitní IP adresa je svázaný se všemi veřejnými IP adresami. Host hlavičky nejsou ověřeny.

Jako alternativní řešení použijte middleware filtrování hostitelů. Middleware pro filtrování hostitelů poskytuje balíček Microsoft.AspNetCore.HostFiltering , který je implicitně poskytován pro aplikace ASP.NET Core. Middleware se přidá voláním CreateDefaultBuilderAddHostFiltering:

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

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

Middleware filtrování hostitelů je ve výchozím nastavení zakázaný. Chcete-li povolit middleware, definujte AllowedHosts klíč v/appsettings.jsonappsettings.{Environment}.json . Hodnota je seznam názvů hostitelů oddělený středníkem bez čísel portů:

appsettings.json:

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

Poznámka

Middleware forwarded Headers má AllowedHosts také možnost. Middleware předávané hlavičky a middleware filtrování hostitelů mají podobné funkce pro různé scénáře. Nastavení AllowedHosts middlewaru Forwarded Headers je vhodné, když Host se hlavička nezachová při předávání požadavků pomocí reverzního proxy serveru nebo nástroje pro vyrovnávání zatížení. Nastavení AllowedHosts middlewaru filtrování hostitelů je vhodné, pokud Kestrel se používá jako veřejný hraniční server nebo když se hlavička Host přímo předá.

Další informace o middlewaru Forwarded Headers najdete v tématu Konfigurace ASP.NET Core pro práci s proxy servery a nástroji pro vyrovnávání zatížení.

Konfigurace přenosu Libuv

Pro projekty, které vyžadují použití knihovny Libuv (UseLibuv):

  • Přidejte závislost balíčku Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv do souboru projektu aplikace:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />

  • Zavolejte UseLibuv na 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>();
            });
}

Vyprazdňování požadavků HTTP/1.1

Otevírání připojení HTTP je časově náročné. Pro PROTOKOL HTTPS je také náročný na prostředky. Kestrel Proto se pokusíte znovu použít připojení podle protokolu HTTP/1.1. Tělo požadavku musí být plně využité, aby bylo možné znovu použít připojení. Aplikace vždy nevyužívá text požadavku, například POST požadavky, ve kterých server vrací přesměrování nebo odpověď 404. POSTV případě přesměrování:

  • Klient už možná odeslal část POST dat.
  • Server zapíše odpověď 301.
  • Připojení nelze použít pro nový požadavek, dokud POST se data z předchozího textu požadavku plně nepřečtou.
  • Kestrel se pokusí vyprázdnit tělo požadavku. Vyprázdnění textu požadavku znamená čtení a zahození dat bez jejich zpracování.

Proces vyprazdňování představuje kompromis mezi povolením opětovného použití připojení a časem potřebným k vyprázdnění zbývajících dat:

  • Vyprazdňování má časový limit 5 sekund, který není možné konfigurovat.
  • Pokud se před vypršením časového limitu nepřečtou všechna data zadaná Content-Length hlavičkou nebo Transfer-Encoding záhlaví, připojení se zavře.

Někdy může být vhodné žádost okamžitě ukončit před napsání odpovědi nebo po ní. Klienti můžou mít například omezující limit dat, takže omezení nahraných dat může být prioritou. V takových případech ukončete požadavek voláním HttpContext.Abort z kontroleru, Razor stránky nebo middlewaru.

Existuje upozornění na volání Abort:

  • Vytváření nových připojení může být pomalé a nákladné.
  • Neexistuje žádná záruka, že klient před ukončením připojení přečte odpověď.
  • Volání Abort by mělo být vzácné a vyhrazeno pro závažné případy chyb, nikoli běžné chyby.
    • Zavolejte Abort jenom v případech, kdy je potřeba vyřešit konkrétní problém. Volání například v Abort případě, že se klienti se zlými úmysly zkouší POST data nebo když v kódu klienta dojde k chybě, která způsobuje velké nebo velké množství požadavků.
    • Nevolejte Abort běžné chybové situace, například HTTP 404 (Nenalezena).

Volání httpResponse.CompleteAsync před voláním Abort zajistí, že server dokončil zápis odpovědi. Chování klienta ale není předvídatelné a nemusí před přerušením připojení číst odpověď.

Tento proces se u protokolu HTTP/2 liší, protože protokol podporuje přerušení jednotlivých datových proudů požadavků bez zavření připojení. Časový limit pětisekundového vyprázdnění se nepoužije. Pokud jsou po dokončení odpovědi nějaká nepřečtená data požadavku, odešle server rámec HTTP/2 RST. Další datové rámce textu požadavku se ignorují.

Pokud je to možné, je lepší, aby klienti využili hlavičku požadavku Expect: 100-continue a počkejte, než server odpoví, než začne odesílat text požadavku. To klientovi dává příležitost prozkoumat odpověď a přerušit před odesláním nepotřebných dat.

Další prostředky