Kestrelimplementace webového serveru v ASP.NET Core

  • Článek
  • 28 min ke čtení

Tom Dykstra, Chris Ross a Stephen Halter

Kestrelje webový server pro různé platformy pro ASP.NET Core. Kestrelje webový server, který je ve výchozím nastavení zahrnutý a povolený v šablonách projektů ASP.NET Core.

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

  • HTTPS
  • HTTP/2 (s výjimkou macOS†)
  • Neprůhlhlý upgrade použitý k povolení webSockets
  • Sokety unixu pro vysoký výkon za Nginx

†HTTP/2 bude podporován v macOS v budoucí verzi.

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

Začínáme

ASP.NET Core šablony projektů 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 WebApplicationBuilderv tématu Minimální přehled rozhraní API

Volitelné klientské certifikáty

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

Další materiály

Poznámka

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

Kestrelje webový server pro různé platformy pro ASP.NET Core. Kestrelje webový server, který je ve výchozím nastavení zahrnutý a povolený v šablonách projektů ASP.NET Core.

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

  • HTTPS
  • HTTP/2 (s výjimkou macOS†)
  • Neprůhlhlý upgrade použitý k povolení webSockets
  • Sokety unixu pro vysoký výkon za Nginx

†HTTP/2 bude podporován v macOS 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 (jak stáhnout)

Začínáme

ASP.NET Core šablony projektů 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ůrcev 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 tématu Volitelné klientské certifikáty.

Další materiály

Poznámka

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

Kestrelje webový server pro různé platformy pro ASP.NET Core. Kestrelje 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ůhlhlý upgrade použitý k povolení webSockets
  • Sokety unixu pro vysoký výkon za Nginx
  • HTTP/2 (s výjimkou macOS†)

†HTTP/2 bude podporován v macOS 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 (jak stáhnout)

Podpora HTTP/2

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

†HTTP/2 bude podporován v macOS v budoucí verzi. •Kestrel má omezenou podporu http/2 v Windows Server 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ý. Certifikát vygenerovaný pomocí algoritmu ECDSA (Elliptic Curve Digital Signature Algorithm) může být nutný k zabezpečení připojení TLS.

Pokud je vytvořeno připojení HTTP/2, HttpRequest.Protocol hlásí HTTP/2.

Počínaje .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.Protocol .

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

Kestrel může být používán sám 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 více 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í vyžadován reverzní proxy server, může být vhodné použít reverzní proxy server.

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šte vyrovnávání zatížení a zabezpečenou konfiguraci 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.

Upozornění

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

Kestrelv aplikacích ASP.NET Core

ASP.NET Core šablony projektů používají Kestrel ve výchozím nastavení. Volání Program.csmetody UseKestrelv :ConfigureWebHostDefaults

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 sestavení hostitele naleznete v části Nastavení hostitele a výchozího nastavení tvůrcev 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 zvlášť užitečné v nasazeních orientovaných na internet.

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 nastavit také pomocí zprostředkovatele konfigurace. Například poskytovatel konfigurace souboru může načíst Kestrel konfiguraci z appsettings.json nebo appsettings.{Environment}.json 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 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 udržování naživu

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 klientských připojení

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

Existuje samostatný limit pro připojení, která byla upgradována z HTTP nebo HTTPS na jiný protokol (například v požadavku WebSockets). Po upgradu připojení se do limitu MaxConcurrentConnections nezapočítávají.

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 textu 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í RequestSizeLimitAttribute atributu 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 po spuštění aplikace ke čtení požadavku, 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ě nakonfigurovat limit.

Když je aplikace za modulem ASP.NET Coremimo proces, omezení velikosti textu požadavku je zakázané, Kestrelprotože služba IIS už limit nastaví.

Minimální objem dat těla 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 klient zvýší rychlost odesílání až na minimum. Během této doby se míra nekontroluje. Období odkladu pomáhá zabránit 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 platí také pro 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í sazby 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řepište minimální limity 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í pro požadavky HTTP/2 k dispozici HttpContext.Features , protože změna limitů rychlosti na základě požadavku se obecně nepodporuje pro HTTP/2 kvůli podpoře protokolu pro multiplexování požadavků. Stále IHttpMinRequestBodyDataRateFeature 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, IHttpMinRequestBodyDataRateFeature.MinDataRatenull a to 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ček požadavků

RequestHeadersTimeout

Získá nebo nastaví maximální dobu, po kterou server stráví přijímáním 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 záhlaví, 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 zadána 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 označ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 jsou podobné hlavičce HTTP, s výjimkou toho, že se po odeslání textu odpovědi odešlou. Pro službu IIS a HTTP.sys jsou podporovány pouze přívěsy s odpověďmi 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 byla pro odpověď podporována přívěsy.
  • DeclareTrailer přidá název daného 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.

Resetovat

Resetování umožňuje serveru resetovat požadavek HTTP/2 se zadaným kódem chyby. Žádost o obnovení 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.

Upozornění

Velký počet blokujících synchronních vstupně-výstupních operací může vést k hladovění fondu vláken, což způsobí, že aplikace nereaguje. Povolte AllowSynchronousIO jenom 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 v následujících tématech:

Konfigurace koncového bodu

Ve výchozím nastavení ASP.NET Core vazby na:

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

Zadejte adresy URL pomocí následujících adres:

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

Hodnota zadaná pomocí těchto přístupů může být jeden nebo více koncových bodů HTTP a HTTPS (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ěchto přístupech najdete v tématu Adresy URL serveru a konfigurace přepsání.

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.

Project šablony konfigurují aplikace tak, aby běžely ve výchozím nastavení na HTTPS, 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 klíč konfigurace hostitele a ASPNETCORE_URLS proměnná prostředí fungují také, ale mají omezení, která jsou uvedena dále v této části (výchozí certifikát musí být k dispozici pro konfiguraci koncového bodu HTTPS).

KestrelServerOptions Konfigurace:

ConfigureEndpointDefaults(ActionListenOptions<>)

Určuje konfiguraci Action , která se má spustit pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults vícekrát nahradí předchozí hodnoty Actionposledním Action zadaným číslem.

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

Poznámka

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

ConfigureHttpsDefaults(ActionHttpsConnectionAdapterOptions<>)

Určuje konfiguraci Action , která se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults vícekrát nahradí předchozí hodnoty Actionposlední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 před voláním ConfigureHttpsDefaultsListen 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 určená Action ke konfiguraci HttpsConnectionAdapterOptions. 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, jestli se mají považovat za neplatné certifikáty, například certifikáty podepsané svým držitelem.
  • location je umístění úložiště pro načtení certifikátu.
  • serverCertificate je certifikát X.509.

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

Podporované konfigurace popsané dále:

  • Žádná konfigurace
  • Nahrazení výchozího certifikátu z konfigurace
  • Změna výchozích nastavení v kódu

Žádná konfigurace

Kestrelhttp://localhost:5000 naslouchá a https://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 . Výchozí schéma konfigurace nastavení aplikace HTTPS je k dispozici pro Kestrel. 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áty podepsané svým držitelem).
  • Každý koncový bod HTTPS, který nezadává certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v části CertifikátyDefault> nebo vývojový certifikát.
{
  "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 libovolný uzel certifikátu je určení certifikátu pomocí polí úložiště certifikátů. Například certifikát CertificatesDefault> 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 jejich přidávání. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v části konfigurace.
  • Oddíl Certificate je volitelný. Certificate Pokud oddíl není zadaný, 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 nespustí se.
  • Tato Certificate část podporuje certifikáty Path–Password i Subject-Store.
  • Libovolný počet koncových bodů je možné tímto způsobem definovat, pokud nezpůsobují konflikty portů.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) vrátí metodu KestrelConfigurationLoader.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 u existujícího 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 jiným oddílem. Používá se pouze poslední konfigurace, pokud Load není explicitně volána u předchozích instancí. Metapackage nevolá Load , aby se mohl nahradit výchozí oddíl konfigurace.
  • KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptionsEndpoint přetížení, takže koncové body kódu a konfigurace se můžou nakonfigurovat 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ělo 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 pro SNI

Označení názvu serveru (SNI) se dá použít k hostování více domén na stejné IP adrese a portu. Aby funkce SNI fungovala, klient odešle název hostitele pro zabezpečenou relaci na server během 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 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ěží na cílovém rozhraní netcoreapp2.1 nebo novějším. Při net461 nebo novějším volání se vyvolá zpětná volání, ale name vždy je null. To name je také null v případě, že klient nezadá parametr názvu hostitele v handshake protokolu TLS.
  • Všechny weby běží na stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu napříč několika 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 bajtu v připojení Protokolování připojení je užitečné pro řešení potíží s nízkou úrovní komunikace, například při šifrování TLS a za proxy servery. Pokud UseConnectionLogging je umístěn dříve UseHttps, zašifrovaný provoz se zaprotokoluje. Pokud UseConnectionLogging se umístí za UseHttpsdešifrovaný provoz, zaprotokoluje se.

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

Vytvoření vazby na soket TCP

Metoda Listen vytvoří vazbu na soket TCP a možnosti lambda povolují 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 pomocí ListenOptions. Ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body použijte stejné rozhraní API.

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

V systému macOS, Linux a Windows je možné vytvořit certifikáty pomocí OpenSSL.

Vytvoření vazby se soketem Unix

Poslouchejte na soketu unixu s lepším výkonem pomocí ListenUnixSocket 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 ListenUnixSocket soketu (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 ve skutečnosti vázán 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 aplikace dostupná:

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í:

  • S těmito přístupy se https nedá použít, pokud není v konfiguraci koncového bodu HTTPS k dispozici výchozí certifikát (například pomocí KestrelServerOptions konfigurace nebo konfiguračního souboru, jak je znázorněno výše v tomto tématu).
  • ListenUseUrls Pokud se používají současně 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 ASP.NET Core Modulu.

ListenOptions.Protocol

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

HttpProtocols výčtová hodnota Povolený protokol připojení
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. HTTP/2 vyžaduje, aby klient v handshake protokolu TLS (ALPN) vybral protokol HTTP/2; jinak se výchozí nastavení připojení k HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota pro libovolný koncový bod 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íčů:
    • Tři tečkovaná křivka 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] Ve výchozím nastavení je podporována tři tečka P-256 [FIPS186].

Následující příklad povoluje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

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

Pomocí middlewaru připojení můžete filtrovat handshakes protokolu TLS na základě připojení pro konkrétní šifry v případě potřeby.

Následující příklad vyvolá NotSupportedException jakýkoli šifrovací algoritmus, který aplikace nepodporuje. Případně definujte a porovnejte 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 se dá použít k filtrování handshake 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čítání Kestrel .

Následující appsettings.json příklad naváže HTTP/1.1 jako výchozí protokol připojení pro všechny koncové body:

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

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

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

Protokoly zadané v kódu přepisují hodnoty nastavené konfigurací.

Předpony adres URL

Pokud používáte UseUrls--urls argument příkazového řádku, urls konfigurační klíč hostitele nebo ASPNETCORE_URLS proměnnou prostředí, můžou být předpony adresy URL v libovolném z následujících formátů.

Platné jsou jenom předpony adresy URL HTTP. Kestrel nepodporuje HTTPS při konfiguraci vazeb 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 speciální. Nic, co se nerozpoznalo jako platná IP adresa nebo localhost se sváže se všemi IP adresami 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 služba IIS, Nginx nebo Apache.

    Upozornění

    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/

    Při 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 rozhraní zpětné smyčky, Kestrel nepodaří se spustit. Pokud některé z rozhraní zpětné smyčky není z jakéhokoli jiného důvodu dostupné (nejčastěji proto, že protokol IPv6 není podporovaný), Kestrel zaznamená upozornění.

Filtrování hostitele

I když Kestrel podporuje konfiguraci založenou na předponách, jako http://example.com:5000je , Kestrel do značné míry ignoruje název hostitele. Hostitel localhost je speciální případ, který se používá pro vazbu na adresy zpětné smyčky. Jakýkoli jiný hostitel, než je explicitní IP adresa, se sváže se všemi veřejnými IP adresami. Host hlavičky se neověřují.

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 ASP.NET Core aplikace. 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 pro přeposílané hlavičky má AllowedHosts také možnost. Middleware pro předávání hlaviček 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í hostitele je vhodné, pokud Kestrel se používá jako veřejný hraniční server nebo když Host je hlavička přímo předána.

Další informace o middlewaru předávaných hlaviček 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 HTTPS je to také náročné na prostředky. Kestrel Proto se pokusíte znovu použít připojení podle protokolu HTTP/1.1. Aby bylo možné znovu použít připojení, musí být plně využito tělo požadavku. Aplikace vždy nevyužívají tělo požadavku, například POST požadavky, ve kterých server vrátí přesměrování nebo odpověď 404. V případě POST-redirect:

  • 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 vyprázdnění je kompromisem mezi povolením opětovného použití připojení a časem, který trvá vyprázdnit zbývající data:

  • Vyprázdnění má časový limit 5 sekund, což není možné konfigurovat.
  • Pokud se před vypršením časového limitu nepřečtou všechna data zadaná Content-LengthTransfer-Encoding v záhlaví, připojení se zavře.

Někdy může být vhodné žádost okamžitě ukončit před zápisem 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.

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

  • Vytváření nových připojení může být pomalé a nákladné.
  • Není zaručeno, ž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é chybové případy, ne běžné chyby.
    • Volání pouze Abort v případech, kdy je potřeba vyřešit konkrétní problém. Volání Abort například v případě, že se klienti se zlými úmysly zkouší data nebo když dojde k POST chybě v kódu klienta, který způsobuje velké nebo velké množství požadavků.
    • Nevolejte běžné Abort chybové situace, jako je 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 pro PROTOKOL HTTP/2 liší, protože protokol podporuje přerušení datových proudů jednotlivých 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 textu požadavku, server odešle 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ší materiály