Kestrelimplementace webového serveru v ASP.NET Core

Tom Dykstra, Chrisa Stephen Halter

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

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

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

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

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

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

Začínáme

ASP.NET Core projektů používají Kestrel ve výchozím nastavení. V souboru Program.cs ConfigureWebHostDefaults volá metoda 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 částech Nastavení hostitele a Výchozí nastavení tvůrce v nástroji Obecný hostitel .NET v ASP.NET Core .

Volitelné klientské certifikáty

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

Další zdroje informací

Poznámka

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

Kestrelje webový server pro více platforem pro ASP.NET Core. Kestrelje webový server, který je ve výchozím nastavení součástí ASP.NET Core projektů.

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

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

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

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

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

Podpora HTTP/2

Protokol HTTP/2 je k dispozici ASP.NET Core aplikacím, pokud jsou splněny následující základní požadavky:

†HTTP/2 bude v macOS podporován v budoucí verzi. ‡Kestrelmá omezenou podporu pro HTTP/2 na 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ý. K zabezpečení připojení TLS může být nutný certifikát vygenerovaný pomocí algoritmu ECDSA (Elliptic Curve Digital Signature Algorithm).

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

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

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

Kestrelmůžete použít buď sám, nebo s obráceným proxy server, jako je například Internetová informační služba (IIS), Nginxnebo Apache. Reverzní proxy server přijímá požadavky HTTP ze sítě a předává je do Kestrel .

Kestrel se používá jako webový server s přístupem k internetu:

Kestrel komunikuje přímo s internetem bez zpětného proxy server

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

Kestrel komunikuje nepřímo s internetem prostřednictvím zpětného proxy server, jako je služba IIS, Nginx nebo Apache

Konfigurace s obráceným nebo bez proxy server je podporovaná konfigurace hostování.

Kestrel Používá se jako hraniční server bez zpětného proxy server nepodporuje sdílení stejné IP adresy a portu mezi několika procesy. Pokud je nakonfigurovaný tak, aby naslouchal na portu, zpracovává veškerý provoz tohoto portu bez ohledu Kestrel Kestrel na Host hlavičky požadavků. Reverzní proxy server, který může sdílet porty, má možnost směrovat požadavky na na Kestrel jedinečnou IP adresu a port.

I když není proxy server reverzní funkce, může být proxy server použít opačnou volbu.

Reverzní proxy server:

  • Může omezit zveřejněnou veřejnou oblast 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.

Upozornění

Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci middlewaru s předávánou hlavičkou.

Kestrelv ASP.NET Core aplikacích

ASP.NET Core projektů používají Kestrel ve výchozím nastavení. V souboru Program.cs ConfigureWebHostDefaults volá metoda 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 částech Nastavení hostitele a Výchozí nastavení tvůrce v nástroji Obecný hostitel .NET v ASP.NET Core .

Pokud chcete po zavolání poskytnout další ConfigureWebHostDefaults 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ý server má možnosti konfigurace omezení, které jsou užitečné zejména v Kestrel nasazeních s přístupem k internetu.

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

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

using Microsoft.AspNetCore.Server.Kestrel.Core;

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

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

Poznámka

KestrelServerOptions Konfigurace koncových bodů a se zprostředkovateli konfigurace nakonfigurují. Zbývající Kestrel konfigurace musí být nakonfigurovaná v kódu C#.

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

  • Konfigurace Kestrel v Startup.ConfigureServices nástroji :

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

    2. V Startup.ConfigureServices souboru Kestrel načtěte oddíl konfigurace Kestrel do konfigurace nástroje :

      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 souboru Program.cs načtěte Kestrel oddíl konfigurace do konfigurace souboru Kestrel :

    // 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 výše uvedené přístupy fungují s libovolným poskytovatelem konfigurace.

Časový limit pro keep-alive

KeepAliveTimeout

Získá nebo nastaví časový limit udržovat. 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 je možné 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 u požadavku WebSockets) existuje samostatné omezení. Po upgradu připojení se nepočítá na základě MaxConcurrentConnections limitu.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

Ve výchozím nastavení je maximální počet připojení 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ý postup pro 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řepsat nastavení u konkrétního požadavku v middleware:

app.Run(async (context) =>
{
    context.Features.Get<IHttpMaxRequestBodySizeFeature>()
        .MaxRequestBodySize = 10 * 1024;

    var minRequestRateFeature = 
        context.Features.Get<IHttpMinRequestBodyDataRateFeature>();
    var minResponseRateFeature = 
        context.Features.Get<IHttpMinResponseDataRateFeature>();

    if (minRequestRateFeature != null)
    {
        minRequestRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

    if (minResponseRateFeature != null)
    {
        minResponseRateFeature.MinDataRate = new MinDataRate(
            bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    }

Výjimka je vyvolána, pokud aplikace po zahájení aplikace nakonfiguruje limit na žádost. Existuje IsReadOnly vlastnost, která určuje, zda MaxRequestBodySize je vlastnost ve stavu jen pro čtení, což znamená, že je příliš pozdě pro konfiguraci limitu.

pokud je aplikace spouštěna mimo proces za modulem ASP.NET Core, Kestrel je limit velikosti textu požadavku zakázán, protože služba IIS již tento limit nastavuje.

Minimální rychlost těla zprávy požadavku

MinRequestBodyDataRate MinResponseDataRate

Kestrel kontroluje každou sekundu, pokud data přicházejí za zadanou rychlost v bajtech za sekundu. Pokud frekvence klesne pod minimální hodnotu, vypršel časový limit připojení. Doba odkladu je doba, která Kestrel klientovi umožní zvýšit rychlost odesílání až na minimum; frekvence není v této době kontrolována. Doba odkladu pomáhá vyhnout se vyřazení připojení, která při počátečním posílání dat zpomalují rychlost, kvůli pomalému spuštění protokolu TCP.

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

Pro odpověď platí také minimální sazba. Kód pro nastavení limitu požadavku a limit odezvy je stejný, s výjimkou, RequestBody že existují nebo Response v názvech vlastností a rozhraní.

Tady je příklad, který ukazuje, jak nakonfigurovat minimální sazby dat v programu 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řepsat minimální limity přenosové rychlosti na žádost 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));
    }

IHttpMinResponseDataRateFeatureOdkazovaná v předchozí ukázce není k dispozici HttpContext.Features pro požadavky HTTP/2, protože Změna omezení přenosové rychlosti u jednotlivých požadavků je obecně Nepodporovaná pro HTTP/2 kvůli podpoře protokolu pro multiplexování požadavků. IHttpMinRequestBodyDataRateFeature HttpContext.Features Pro požadavky HTTP/2 se ale stále používá, protože omezení četnosti čtení může být pořád zcela zakázané na základě jednotlivých požadavků nastavením IHttpMinRequestBodyDataRateFeature.MinDataRate na null i pro požadavek HTTP/2. Když se pokusíte o jeho navýšení IHttpMinRequestBodyDataRateFeature.MinDataRate nebo pokus o jeho nastavení na jinou hodnotu než, null vygeneruje se NotSupportedException mu požadavek HTTP/2.

Omezení přenosové rychlosti pro všechny servery jsou nakonfigurovaná přes KestrelServerOptions.Limits protokol HTTP/1. x i pro připojení HTTP/2.

Časový limit hlaviček žádostí

RequestHeadersTimeout

Získá nebo nastaví maximální dobu, po kterou server stráví příjem 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 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 hlaviček

Dekodér HPACK dekomprimuje hlavičky HTTP pro připojení HTTP/2. Http2.HeaderTableSize omezuje velikost kompresní tabulky hlaviček, kterou používá dekodér HPACK. Hodnota je uvedena 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 Určuje maximální povolenou velikost datové části rámce připojení HTTP/2 přijatého nebo odesílaného serverem. Hodnota je uvedena v oktetech a musí být v rozmezí 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ček požadavku. Toto omezení se vztahuje na název i hodnotu v jejich komprimovaných a nekomprimovaných reprezentujcích. Hodnota musí být větší než nula (0).

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

Výchozí hodnota je 8 192.

Velikost okna počátečního připojení

Http2.InitialConnectionWindowSize Určuje maximální velikost textu požadavku v bajtech, které jsou v jednom okamžiku agregovány v rámci všech požadavků (datových proudů) na připojení. Žádosti jsou také omezené pomocí Http2.InitialStreamWindowSize . Hodnota musí být větší než 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 Určuje maximální velikost textu požadavku v bajtech na jednu žádost (Stream) na jednom místě. Žádosti jsou také omezené pomocí Http2.InitialConnectionWindowSize . Hodnota musí být větší než 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).

Karoseri

Hlavičky HTTP se podobají hlavičkám HTTP s tím rozdílem, že se odesílaly po odeslání textu odpovědi. Pro IIS a HTTP.sys se podporují pouze hlavičky s 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 příkladu kódu:

  • SupportsTrailers zajišťuje, že odpověď podporuje upoutávky.
  • DeclareTrailer přidá do hlavičky odpovědi daný Trailer název hlavičky. Deklarování upoutávky odpovědi 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í upoutávku.

Resetovat

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í vstup/výstup. Výchozí hodnota je false.

Upozornění

Velký počet blokujících synchronních vstupně-výstupních operací může vést ke vyčerpání fondu vláken, což aplikaci nereaguje. Povolit pouze AllowSynchronousIO při použití knihovny, která nepodporuje asynchronní vstupně-výstupní operace.

Následující příklad povoluje synchronní vstupně-výstupní operace:

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

Informace o dalších Kestrel možnostech a omezeních najdete v těchto tématech:

Konfigurace koncového bodu

ve výchozím nastavení ASP.NET Core váže k:

  • 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 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řístupůch najdete v tématu adresy URL serveru a potlačení konfigurace.

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

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

šablony Project konfigurují aplikace tak, aby se ve výchozím nastavení spouštěly pomocí protokolu https a zahrnovaly přesměrování HTTPS a podporu HSTS.

Volání Listen nebo ListenUnixSocket metody pro KestrelServerOptions konfiguraci 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í fungují také, ale mají omezení zaznamenaná později v této části (pro konfiguraci koncového bodu https musí být k dispozici výchozí certifikát).

KestrelServerOptions rozšířeného

ConfigureEndpointDefaults (akce <ListenOptions> )

Určuje konfiguraci Action , která se spustí pro každý zadaný koncový bod. Volání několikrát ConfigureEndpointDefaults nahrazuje předchozí Action Action zadanou parametr s.

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

Poznámka

Koncové body vytvořené voláním Listen před voláním ConfigureEndpointDefaults nebudou použity výchozí hodnoty.

ConfigureHttpsDefaults (akce <HttpsConnectionAdapterOptions> )

Určuje konfiguraci Action , která se má spustit pro každý koncový bod HTTPS. Volání několikrát ConfigureHttpsDefaults nahrazuje předchozí Action Action zadanou parametr s.

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

Poznámka

Koncové body vytvořené voláním Listen před voláním ConfigureHttpsDefaults nebudou použity výchozí hodnoty.

Konfigurace (IConfiguration)

Vytvoří zavaděč konfigurace pro nastavení Kestrel , který IConfiguration jako vstup převezme. Konfigurace musí být v oboru konfiguračního oddílu pro Kestrel .

ListenOptions.UseHttps

Nakonfigurujte Kestrel pro použití protokolu HTTPS.

ListenOptions.UseHttps SND

  • UseHttps: Nakonfigurujte Kestrel pro použití HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurován žá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 ukazatelů

  • 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 Action pro konfiguraci HttpsConnectionAdapterOptions . Vrátí 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ě, 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í být poskytnut minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

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

Žádná konfigurace

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

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

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

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

  • Pokud chcete povolit použití neplatných certifikátů (například certifikátů podepsaných svým držitelem), nastavte možnost AllowInvalid true na .
  • Jakýkoli koncový bod HTTPS, který nezadá certifikát (v následujícím příkladu HttpsDefaultCert), se vrátí zpět k certifikátu definovanému v části Výchozí certifikáty 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 zadání certifikátu pomocí polí úložiště certifikátů. Například výchozí certifikát Certifikáty > je možné 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:

  • V názvech koncových bodů se velká a malá písmena nelišují. Například a HTTPS Https jsou platné.
  • Parametr Url je vyžadován pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně s tím rozdílem, že je Urls omezený na jednu hodnotu.
  • Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší Urls úrovně, a nikoli je přidávají. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfiguračním oddílu.
  • Oddíl Certificate je volitelný. Pokud Certificate oddíl nezadáte, použije 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.
  • Oddíl Certificate podporuje certifikáty PathPassword (Heslo cesty) i Subject Store – (Úložiště předmětu).
  • Tímto způsobem lze definovat libovolný počet koncových bodů, pokud nezpůsobí konflikty portů.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) vrací KestrelConfigurationLoader s metodou .Endpoint(string name, listenOptions => { }) , kterou je možné použít k doplnění nastavení nakonfigurovaného koncového bodu:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader je možné přímo přistupovat a pokračovat v iteraci stávajícího zavaděče, jako je například ten, který poskytuje CreateDefaultBuilder .

  • Konfigurační oddíl pro jednotlivé koncové body je k dispozici u možností v metodě , aby bylo možné číst Endpoint vlastní nastavení.
  • Více konfigurací se může načíst tak, že options.Configure(context.Configuration.GetSection("{SECTION}")) se znovu zavolá s jiným oddílem. Použije se pouze poslední konfigurace, pokud Load není explicitně volána pro předchozí instance. Metabalíček nevolá , takže je možné nahradit jeho výchozí konfigurační Load oddíl.
  • KestrelConfigurationLoader zrcadlí rodinu rozhraní API z jako přetížení, takže koncové body kódu a konfigurace je možné nakonfigurovat Listen KestrelServerOptions na stejném Endpoint místě. Tato přetížení nevyužívají názvy a využívají pouze výchozí nastavení z konfigurace.

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

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

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

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

Kestrel podpora SNI

Indikace názvu serveru (SNI) je možné použít k hostování více domén na stejné IP adrese a portu. Aby SNI fungovala, 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á certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje po metodě handshake protokolu TLS.

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

Podpora SNI vyžaduje:

  • Spuštění v cílovém rozhraní netcoreapp2.1 nebo novějším V net461 systému nebo novějším je zpětné volání vyvoláno, ale name je vždy null . je také v případě, že klient při ověřování TLS handshake nezadá parametr názvu name null hostitele.
  • Všechny weby běží na 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ím UseConnectionLogging vysíláte protokoly na úrovni ladění pro komunikaci na úrovni byte u připojení. Protokolování připojení je užitečné při řešení potíží při komunikaci nízké úrovně, například během šifrování TLS a za nástroji prox. Pokud UseConnectionLogging je umístěný před , UseHttps šifrovaný provoz se zaprotokoluje. Pokud UseConnectionLogging se umístí za , 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 se váže na soket TCP a možnost lambda povoluje 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 konfiguruje HTTPS pro koncový bod pomocí ListenOptions . Stejné rozhraní API použijte ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body.

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

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

Vytvoření vazby k unixovému soketu

Naslouchejte soketu Unixu s příkazem , který zlepšuje výkon serveru 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 > location > proxy_pass položku na http://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} je název soketu poskytnutého ListenUnixSocket pro (například kestrel-test.sock v předchozím příkladu).
  • Ujistěte se, že je soket zapisovatelný pro Nginx (například chmod go+w /tmp/kestrel-test.sock ).

Port 0

Když je zadané číslo 0 portu, Kestrel dynamicky se sváže s dostupným portem. Následující příklad ukazuje, jak zjistit, který port je Kestrel skutečně svá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 indikuje dynamický port, na kterém je aplikace k dispozici:

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

Omezení

Koncové body nakonfigurujte následujícími přístupy:

  • 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 kódu s jinými servery než Kestrel . Je však třeba mít na paměti následující omezení:

  • HTTPS nelze s těmito přístupy použít, pokud není v konfiguraci koncového bodu HTTPS poskytnut výchozí certifikát (například pomocí konfigurace nebo konfiguračního souboru, jak je uvedeno výše KestrelServerOptions v tomto tématu).
  • Pokud se současně používají přístupy Listen i , koncové body UseUrls Listen 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ď pomocí Listen , nebo UseUrls . Další informace najdete v tématu ASP.NET Core Module.

ListenOptions.Protocols

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

HttpProtocols hodnota výčtu Povolený protokol připojení
Http1 Pouze HTTP/1.1. Je možné použít s protokolem TLS nebo bez něj.
Http2 Pouze HTTP/2. Bez protokolu TLS se může používat jenom v případě, že klient podporuje režim předchozí znalostní báze.
Http1AndHttp2 HTTP/1.1 a HTTP/2. HTTP/2 vyžaduje, aby klient v rámci metody handshake protokolu TLS (ALPN) vybral http/2. v opačném případě se připojení nastaví jako výchozí HTTP/1.1.

Výchozí ListenOptions.Protocols hodnota pro libovolný koncový bod je HttpProtocols.Http1AndHttp2 .

Omezení TLS pro HTTP/2:

  • TLS verze 1,2 nebo novější
  • Opětovné vyjednávání je zakázané.
  • Komprese vypnuta
  • Minimální velikosti dočasného výměny klíčů:
    • Diffie-Hellman eliptické křivky (ECDH) [ RFC4492 ] : 224 bity minima
    • Omezené pole Diffie-Hellman (DHE) [ TLS12 ] : 2048 bity minima
  • Šifrovací sada není zakázaná.

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

Následující příklad povoluje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení TLS zabezpečuje pomocí zadaného certifikátu:

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

Pomocí middleware připojení můžete v případě potřeby filtrovat handshake na základě jednotlivých připojení pro konkrétní šifry.

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

Pro šifrovací algoritmus 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í lze také nakonfigurovat 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 systému Linux se CipherSuitesPolicy dá použít k filtrování ověřování TLS metodou handshake na základě jednotlivých 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,
                    // ...
                });
        };
    });
});

Nastavit protokol z konfigurace

CreateDefaultBuilder Při serverOptions.Configure(context.Configuration.GetSection("Kestrel")) načítání konfigurace volá ve výchozím nastavení Kestrel .

Následující appsettings.json příklad vytvoří 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ří 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řepisu kódu nastavených podle konfigurace

Předpony adresy URL

Při použití UseUrls , --urls argumentu 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 některém z následujících formátů.

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

  • Adresa IPv4 s číslem portu

    http://65.55.39.10:80/
    

    0.0.0.0 je zvláštní případ, který se váže ke všem adresám IPv4.

  • Adresa IPv6 s číslem portu

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

    [::] je ekvivalentem protokolu IPv4 pro protokol IPv6 0.0.0.0 .

  • Název hostitele s číslem portu

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

    Názvy hostitelů, * a + nejsou speciální. Cokoli se nerozpoznalo jako platná IP adresa nebo localhost se váže ke všem IP adresám IPv4 a IPv6. pokud chcete navazovat různé názvy hostitelů na různé ASP.NET Core aplikace na stejném portu, použijte HTTP.sys nebo reverzní proxy server, jako je IIS, Nginx nebo Apache.

    Upozornění

    Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci pro přesměrované hlavičky middleware.

  • localhostNázev hostitele 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í se Kestrel pokusí vytvořit propojení s rozhraními zpětné smyčky IPv4 i IPv6. Pokud je požadovaný port používán jinou službou na rozhraní zpětné smyčky, Kestrel spuštění se nespustí. Pokud je rozhraní zpětné smyčky v žádném jiném případě nedostupné (většinou vzhledem k tomu, že protokol IPv6 není podporovaný), Kestrel zaznamená upozornění.

Filtrování hostitele

I když Kestrel podporuje konfiguraci na základě prefixů http://example.com:5000 , jako je, Kestrel z velké části se název hostitele ignoruje. Hostitel localhost je zvláštní případ, který se používá pro vazbu na adresy zpětné smyčky. Každý hostitel, který je jiný než explicitní IP adresa, se váže na všechny veřejné IP adresy. Host hlavičky nejsou ověřené.

Jako alternativní řešení použijte middleware pro filtrování hostitele. middleware pro filtrování hostitele poskytuje balíček Microsoft. AspNetCore. HostFiltering , který je implicitně k dispozici pro ASP.NET Core aplikace. Middleware je přidána pomocí CreateDefaultBuilder , který volá AddHostFiltering :

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

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

Middleware pro filtrování hostitele je ve výchozím nastavení zakázáno. Chcete-li povolit middleware, definujte AllowedHosts klíč v appsettings.json / appSettings. <EnvironmentName> . JSON. Hodnota je seznam názvů hostitelů oddělených středníkem bez čísel portů:

appsettings.json:

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

Poznámka

Middleware předávaných hlaviček má také AllowedHosts možnost. Middleware předávaných hlaviček a middleware pro filtrování hostitele mají podobné funkce pro různé scénáře. Nastavení AllowedHosts pomocí předávaných middlewarových hlaviček je vhodné v případě, že Host Hlavička není zachována při předávání požadavků pomocí reverzního proxy server nebo nástroje pro vyrovnávání zatížení. Nastavení AllowedHosts pomocí middlewaru pro filtrování hostitele je vhodné Kestrel , pokud 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í Libuv ( UseLibuv ):

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

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Zavolat 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žadavku HTTP/1.1

Otevírání připojení HTTP je časově náročné. V případě protokolu HTTPS je také náročný na prostředky. Proto se Kestrel pokusí znovu použít připojení podle protokolu HTTP/1.1. Aby bylo možné připojení znovu použít, musí být text žádosti plně spotřebovaný. Aplikace nespotřebovává text žádosti vždycky, například POST žádosti, kde server vrací přesměrování nebo odpověď 404. V POST případě případu přesměrování:

  • Klient již mohl odeslat část POST dat.
  • Server zapisuje odpověď 301.
  • Připojení nelze použít pro novou žádost, dokud nebudou POST data z předchozího textu požadavku plně přečtena.
  • Kestrel pokusí se vyprázdnit tělo žádosti. Vyprázdnit tělo žádosti znamená čtení a zahození dat bez jejich zpracování.

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

  • Vyprázdnění má časový limit pět sekund, což není konfigurovatelné.
  • Pokud nebyla všechna data zadaná v Content-Length Transfer-Encoding hlavičce nebo přečtena před časovým limitem, připojení je zavřeno.

Někdy je možné, že budete chtít žádost ukončit hned nebo po zápisu odpovědi. Například klienti mohou mít omezující data, takže omezení nahraných dat může být prioritou. V takových případech pro ukončení žádosti zavolejte HttpContext. Abort z kontroleru, Razor stránky nebo middlewaru.

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

  • Vytváření nových připojení může být pomalé a nákladné.
  • Není zaručeno, že klient před zavřením připojení přečetl odpověď.
  • Volání Abort by mělo být vzácné a vyhrazené pro závažné chybové případy, ne běžné chyby.
    • Volá se jenom v případě, že je Abort potřeba vyřešit konkrétní problém. Například volejte, Abort Pokud se zlomyslní klienti pokoušejí POST data nebo když dojde k chybě v kódu klienta, která způsobuje velké nebo velké požadavky.
    • Nevolejte Abort pro běžné chybové situace, například HTTP 404 (Nenalezeno).

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

Tento proces se liší od protokolu HTTP/2, protože protokol podporuje přerušování jednotlivých datových proudů požadavků bez ukončení připojení. Nedá se použít 5 sekundový časový limit vyprázdnění. Pokud po dokončení odpovědi dojde k nepřečteným datům textu žádosti, server odešle snímek HTTP/2 RST. Další datové snímky požadavku jsou ignorovány.

Pokud je to možné, je lepší, aby klienti využili hlavičku žádosti očekávat: 100-pokračovat a čekali na odpověď serveru před zahájením odesílání textu žádosti. Díky tomu může klient příležitost před odesláním nepotřebných dat ověřit odpověď a zrušit jejich přerušení.

Další zdroje informací

Kestrelje webový server pro různé platformy pro ASP.NET Core. Kestrelje webový server, který je ve výchozím nastavení součástí ASP.NET Core šablon projektů.

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

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

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

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

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

Podpora HTTP/2

Protokol HTTP/2 je k dispozici ASP.NET Core aplikacím, pokud jsou splněny následující základní požadavky:

†HTTP/2 bude v macOS podporován v budoucí verzi. ‡Kestrelmá omezenou podporu pro HTTP/2 na 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ý. K zabezpečení připojení TLS může být nutný certifikát vygenerovaný pomocí algoritmu ECDSA (Elliptic Curve Digital Signature Algorithm).

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

Protokol HTTP/2 je ve výchozím nastavení zakázaný. Další informace o konfiguraci najdete v částech Kestrel Možnosti a ListenOptions.Protocols.

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

Kestrelmůžete použít buď sám, nebo s obráceným proxy server, jako je například Internetová informační služba (IIS), Nginxnebo Apache. Reverzní proxy server přijímá požadavky HTTP ze sítě a předává je do Kestrel .

Kestrel se používá jako webový server s přístupem k internetu:

Kestrel komunikuje přímo s internetem bez zpětného proxy server

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

Kestrel komunikuje nepřímo s internetem prostřednictvím zpětného proxy server, jako je služba IIS, Nginx nebo Apache.

Podporovanou konfigurací hostování je buď proxy server, nebo bez zpětného nastavení.

Kestrel používá se jako hraniční server bez zpětného proxy server nepodporuje sdílení stejné IP adresy a portu mezi několika procesy. Pokud je nakonfigurovaný tak, aby naslouchal na portu, zpracovává veškerý provoz tohoto portu bez ohledu Kestrel Kestrel na Host hlavičky požadavků. Reverzní proxy server, který může sdílet porty, má možnost směrovat požadavky na na Kestrel jedinečnou IP adresu a port.

I když není proxy server reverzní funkce, může být proxy server použít opačnou volbu.

Reverzní proxy server:

  • Může omezit zveřejněnou veřejnou oblast 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.

Upozornění

Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci middlewaru s předávánou hlavičkou.

Jak používat v Kestrel ASP.NET Core aplikacích

Microsoft.AspNetCore.Server. Kestrel balíček je součástí balíčku Microsoft.AspNetCore.App metapackage.

ASP.NET Core šablony projektů používají Kestrel ve výchozím nastavení. V souboru Program.cs volá kód šablony CreateDefaultBuilder metodu , která volá na UseKestrel pozadí.

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

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

Další informace o hostiteli a jeho vytváření najdete v části CreateDefaultBuilder Nastavení hostitele v tématu ASP.NET Core Webový hostitel .

Pokud chcete po zavolání poskytnout další CreateDefaultBuilder konfiguraci, použijte ConfigureKestrel :

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

Pokud aplikace nenastaví hostitele, před voláním CreateDefaultBuilder volejte UseKestrel ConfigureKestrel :

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

    host.Run();
}

Kestrel Možnosti

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

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

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

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel Možnosti, které jsou nakonfigurované v kódu jazyka C# v následujících příkladech, lze nastavit také pomocí zprostředkovatele konfigurace. Zprostředkovatel konfigurace souboru může například načíst Kestrel konfiguraci z nebo appsettings.json appsettings.{ Soubor Environment}.json:

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

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

  • Konfigurace Kestrel v Startup.ConfigureServices nástroji :

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

    2. V Startup.ConfigureServices souboru Kestrel načtěte oddíl konfigurace Kestrel do konfigurace nástroje :

      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 souboru Program.cs načtěte Kestrel oddíl konfigurace do konfigurace souboru Kestrel :

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

Oba výše uvedené přístupy fungují s libovolným poskytovatelem konfigurace.

Časový limit pro keep-alive

KeepAliveTimeout

Získá nebo nastaví časový limit udržovat. Výchozí hodnota je 2 minuty.

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

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

MaxConcurrentConnections MaxConcurrentUpgradedConnections

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

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

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

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

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í atributu RequestSizeLimitAttribute v metodě akce:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

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

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Přepište nastavení pro konkrétní 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));
    }

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

Pokud aplikace běží mimo proces za modulem ASP.NET Core,je limit velikosti textu požadavku zakázán, protože služba IIS už Kestrel tento limit nastavuje.

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

MinRequestBodyDataRate MinResponseDataRate

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

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

Minimální sazba platí také pro odpověď. Kód pro nastavení limitu požadavků a limitu odpovědi je stejný s výjimkou kódu nebo v RequestBody Response názvech vlastností a rozhraní.

Tady je příklad, který ukazuje, jak nakonfigurovat minimální přenosovou rychlost v souboru Program.cs:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

Přepsání minimálních limitů přenosové 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));
    }

Pro požadavky HTTP/2 není k dispozici žádná funkce rychlosti, na kterou se odkazuje v předchozí ukázce, protože kvůli podpoře multiplexingu požadavků protokolem nepodporuje úpravy omezení přenosové rychlosti pro každý HttpContext.Features požadavek. Omezení přenosové rychlosti na úrovni serveru nakonfigurovaná prostřednictvím stále platí pro připojení KestrelServerOptions.Limits HTTP/1.x i HTTP/2.

Časový limit 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.

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
    serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
});

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

Http2.MaxStreamsPerConnection omezuje počet souběžných streamů požadavků na připojení HTTP/2. Nadbytečné datové proudy se zamítnou.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, 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 zadaná v oktech a musí být větší než nula (0).

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

Výchozí hodnota je 4096.

Maximální velikost rámce

Http2.MaxFrameSize určuje maximální velikost datové části rámce připojení HTTP/2, která se má přijmout. Hodnota se poskytuje v oktetech a musí být mezi 2^14 (16 384) a 2^24-1 (16 777 215).

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

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. Toto omezení platí pro název i hodnotu společně ve svých komprimovaných i nekomprimovaných reprezentacích. Hodnota musí být větší než nula (0).

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

Výchozí hodnota je 8 192.

Velikost počátečního okna připojení

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

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

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

Velikost okna počátečního streamu

Http2.InitialStreamWindowSize označuje maximální počet dat textu požadavku v bajtech, které server na požadavek (stream) do vyrovnávací paměti zasuuje najednou. Požadavky jsou také omezeny pomocí Http2.InitialStreamWindowSize . Hodnota musí být větší nebo rovna 65 535 a menší než 2^31 (2 147 483 648).

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

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

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

Upozornění

Velký počet blokující synchronních vstupně-výstupních operací může vést k tomu, že fond vláken přestane reagovat. Tuto možnost AllowSynchronousIO povolte pouze v případě, že používáte knihovnu, která nepodporuje asynchronní V/V operace.

Následující příklad povolí synchronní vstupně-výstupní operace:

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

Informace o dalších Kestrel možnostech a omezeních najdete v těchto tématu:

Konfigurace koncového bodu

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

  • http://localhost:5000
  • https://localhost:5001 (když je k dispozici místní certifikát pro vývoj)

Adresy URL můžete zadat 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 poskytovaná 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 certifikát pro vývoj:

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

Project šablony konfigurují aplikace tak, aby ve výchozím nastavení běží na HTTPS, a zahrnují přesměrování HTTPS a podporu HSTS.

Voláním Listen metody nebo můžete nakonfigurovat ListenUnixSocket KestrelServerOptions předpony adres URL a porty pro Kestrel .

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

KestrelServerOptions Konfigurace:

ConfigureEndpointDefaults(Action <ListenOptions> )

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

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

Poznámka

U koncových bodů Listen vytvořených voláním ConfigureEndpointDefaults před voláním se nebudou uplatňovat výchozí hodnoty.

ConfigureHttpsDefaults(Akce <HttpsConnectionAdapterOptions> )

Určuje konfiguraci, která Action se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults vícekrát nahradí předchozí Action hodnoty za poslední Action zadané.

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

Poznámka

U koncových bodů Listen vytvořených voláním ConfigureHttpsDefaults před voláním se nebudou uplatňovat výchozí hodnoty.

Configure(IConfiguration)

Vytvoří zavaděč konfigurace pro Kestrel nastavení, které přijímá IConfiguration jako vstup. Konfigurace musí být vymezená konfiguračním oddílem pro Kestrel .

ListenOptions.UseHttps

KestrelNakonfigurujte, aby se protokol HTTPS používat.

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 Action pro konfiguraci HttpsConnectionAdapterOptions . Vrátí 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ě, 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í být poskytnut minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

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

Žádná konfigurace

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

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

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

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

  • Pokud chcete povolit použití neplatných certifikátů (například certifikátů podepsaných svým držitelem), nastavte možnost AllowInvalid true na .
  • Jakýkoli koncový bod HTTPS, který nezadá certifikát (v následujícím příkladu HttpsDefaultCert), se vrátí zpět k certifikátu definovanému v části Výchozí certifikáty 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 zadání certifikátu pomocí polí úložiště certifikátů. Například výchozí certifikát Certifikáty > je možné 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:

  • V názvech koncových bodů se velká a malá písmena nelišují. Například a HTTPS Https jsou platné.
  • Parametr Url je vyžadován pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně s tím rozdílem, že je Urls omezený na jednu hodnotu.
  • Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší Urls úrovně, a nikoli je přidávají. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfiguračním oddílu.
  • Oddíl Certificate je volitelný. Pokud Certificate není oddíl zadaný, použijí se výchozí hodnoty definované v dřívějších scénářích. Pokud nejsou k dispozici žádné výchozí hodnoty, Server vyvolá výjimku a nemůže se spustit.
  • CertificateOddíl podporuje jak heslo cesty – , tak – certifikáty úložiště subjektu.
  • V takovém případě může být definován libovolný počet koncových bodů, pokud to nezpůsobí konflikty portů.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) Vrátí KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) metodu s metodou, kterou lze použít k doplnění nastavení nakonfigurovaného koncového bodu:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

KestrelServerOptions.ConfigurationLoader k pokračování v iteraci u stávajícího zavaděče se dá získat přímý odkaz, jako je třeba ten, který poskytuje CreateDefaultBuilder .

  • Konfigurační oddíl pro každý koncový bod je k dispozici na možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
  • Více konfigurací může být načteno voláním options.Configure(context.Configuration.GetSection("{SECTION}")) znovu s jiným oddílem. Je použita pouze poslední konfigurace, pokud Load není explicitně volána při předchozích instancích. Metapackage nevolá Load , aby se jeho výchozí konfigurační oddíl mohl nahradit.
  • KestrelConfigurationLoader zrcadlí Listen rodinu rozhraní API z KestrelServerOptions as Endpoint přetížení, takže koncové body kódu a konfigurace lze konfigurovat 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

ConfigureEndpointDefaults a ConfigureHttpsDefaults dá se použít ke změně výchozího nastavení pro ListenOptions a HttpsConnectionAdapterOptions , včetně přepsání výchozího certifikátu zadaného v předchozím scénáři. ConfigureEndpointDefaults a ConfigureHttpsDefaults měla by být volána před konfigurací koncových bodů.

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

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

Kestrel Podpora pro SNI

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

Kestrel podporuje SNI prostřednictvím ServerCertificateSelector zpětného volání. Zpětné volání je vyvoláno jednou za připojení, které aplikaci umožní 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. V systému net461 nebo novějším je zpětné volání vyvoláno, ale name je vždy null . nameJe také v null případě, že klient v TLS handshake neposkytne parametr názvu hostitele.
  • Všechny weby běží ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu napříč několika instancemi bez reverzního proxy serveru.
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ListenAnyIP(5005, listenOptions =>
            {
                listenOptions.UseHttps(httpsOptions =>
                {
                    var localhostCert = CertificateLoader.LoadFromStoreCert(
                        "localhost", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var exampleCert = CertificateLoader.LoadFromStoreCert(
                        "example.com", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var subExampleCert = CertificateLoader.LoadFromStoreCert(
                        "sub.example.com", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var certs = new Dictionary<string, X509Certificate2>(
                        StringComparer.OrdinalIgnoreCase);
                    certs["localhost"] = localhostCert;
                    certs["example.com"] = exampleCert;
                    certs["sub.example.com"] = subExampleCert;

                    httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
                    {
                        if (name != null && certs.TryGetValue(name, out var cert))
                        {
                            return cert;
                        }

                        return exampleCert;
                    };
                });
            });
        });

Protokolování připojení

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

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

Vytvoření vazby na soket TCP

ListenMetoda se váže k soketu TCP a pomocí lambda možností povolíte konfiguraci certifikátu X. 509:

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

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

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.

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

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

Vytvoření vazby na soket UNIX

Naslouchat na soketu se systémem UNIX ListenUnixSocket , aby se zlepšil výkon pomocí Nginx, jak je znázorněno v tomto příkladu:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});
  • V souboru Nginx confiuguration nastavte server > location > proxy_pass položku na http://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} je název soketu poskytnutý ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
  • Zajistěte, aby byl soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock ).

Port 0

Když 0 je zadané číslo portu, Kestrel dynamicky se váže k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel 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ž se aplikace spustí, výstup okna konzoly indikuje dynamický port, na který se aplikace dá získat:

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

Omezení

Konfigurace koncových bodů 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é, pokud chcete, aby kód pracoval se servery jiným než Kestrel . Mějte ale na paměti následující omezení:

  • Protokol HTTPS nelze s těmito přístupy použít, pokud není k dispozici výchozí certifikát v konfiguraci koncového bodu HTTPS (například pomocí KestrelServerOptions Konfigurace nebo konfiguračního souboru, jak je uvedeno výše v tomto tématu).
  • Při Listen UseUrls současném použití obou přístupů a Listen koncových bodů se koncové body přepisují UseUrls .

Konfigurace koncového bodu služby IIS

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

ListenOptions. Protocols

ProtocolsVlastnost určuje protokoly HTTP ( HttpProtocols ) povolené pro koncový bod připojení nebo pro server. Přiřaďte hodnotu Protocols vlastnosti z HttpProtocols výčtu.

HttpProtocols hodnota výčtu Povolený protokol připojení
Http1 Pouze HTTP/1.1. Dá se použít s TLS nebo bez něj.
Http2 Pouze HTTP/2. Dá se použít bez TLS jenom v případě, že klient podporuje předchozí režim znalostní báze.
Http1AndHttp2 HTTP/1.1 a HTTP/2. HTTP/2 vyžaduje připojení TLS a ALPN (Application-Layer Protocol Negotiation) ; v opačném případě se připojení nastaví jako výchozí HTTP/1.1.

Výchozí protokol HTTP/1.1.

Omezení TLS pro HTTP/2:

  • TLS verze 1,2 nebo novější
  • Opětovné vyjednávání je zakázané.
  • Komprese vypnuta
  • Minimální velikosti dočasného výměny klíčů:
    • Diffie-Hellman eliptické křivky (ECDH) [ RFC4492 ] : 224 bity minima
    • Omezené pole Diffie-Hellman (DHE) [ TLS12 ] : 2048 bity minima
  • Šifrovací sada není zablokovaná.

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

Následující příklad povoluje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení TLS zabezpečuje pomocí zadaného certifikátu:

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

Volitelně můžete vytvořit IConnectionAdapter implementaci pro filtrování ověřování TLS metodou handshake na základě jednotlivých připojení pro konkrétní šifry:

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

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

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

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

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

        public Stream ConnectionStream { get; }

        public void Dispose()
        {
        }
    }
}

Nastavit protokol z konfigurace

CreateDefaultBuilder Při serverOptions.Configure(context.Configuration.GetSection("Kestrel")) načítání konfigurace volá ve výchozím nastavení Kestrel .

V následujícím appsettings.json příkladu je pro všechny koncové body vytvořen výchozí protokol připojení (http/1.1 a HTTP/2) Kestrel :

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

Následující příklad konfiguračního souboru vytvoří protokol připojení pro konkrétní koncový bod:

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

Protokoly zadané v hodnotách přepisu kódu nastavených podle konfigurace

Konfigurace přenosu Libuv

s vydáním ASP.NET Core 2,1 se Kestrel výchozí přenos už nepoužívá na Libuv, ale vychází ze spravovaných soketů. jedná se o zásadní změnu pro aplikace ASP.NET Core 2,0 upgradované na 2,1, které volá UseLibuv a závisí na jednom z následujících balíčků:

Pro projekty, které vyžadují použití Libuv:

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

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Volání UseLibuv :

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

Předpony adresy URL

Při použití UseUrls , --urls argumentu 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 některém z následujících formátů.

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

  • Adresa IPv4 s číslem portu

    http://65.55.39.10:80/
    

    0.0.0.0 je zvláštní případ, který se váže ke všem adresám IPv4.

  • Adresa IPv6 s číslem portu

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

    [::] je ekvivalentem protokolu IPv4 pro protokol IPv6 0.0.0.0 .

  • Název hostitele s číslem portu

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

    Názvy hostitelů, * a + nejsou speciální. Cokoli se nerozpoznalo jako platná IP adresa nebo localhost se váže ke všem IP adresám IPv4 a IPv6. pokud chcete navazovat různé názvy hostitelů na různé ASP.NET Core aplikace na stejném portu, použijte HTTP.sys nebo reverzní proxy server, jako je IIS, Nginx nebo Apache.

    Upozornění

    Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci pro přesměrované hlavičky middleware.

  • localhostNázev hostitele 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í se Kestrel pokusí vytvořit propojení s rozhraními zpětné smyčky IPv4 i IPv6. Pokud je požadovaný port používán jinou službou na rozhraní zpětné smyčky, Kestrel spuštění se nespustí. Pokud je rozhraní zpětné smyčky v žádném jiném případě nedostupné (většinou vzhledem k tomu, že protokol IPv6 není podporovaný), Kestrel zaznamená upozornění.

Filtrování hostitele

I když Kestrel podporuje konfiguraci na základě prefixů http://example.com:5000 , jako je, Kestrel z velké části se název hostitele ignoruje. Hostitel localhost je zvláštní případ, který se používá pro vazbu na adresy zpětné smyčky. Každý hostitel, který je jiný než explicitní IP adresa, se váže na všechny veřejné IP adresy. Host hlavičky nejsou ověřené.

Jako alternativní řešení použijte middleware pro filtrování hostitele. middleware pro filtrování hostitele poskytuje balíček Microsoft. AspNetCore. HostFiltering , který je zahrnutý v Microsoft.AspNetCore.App metapackage (ASP.NET Core 2,1 nebo 2,2). Middleware je přidána pomocí CreateDefaultBuilder , který volá AddHostFiltering :

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

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

Middleware pro filtrování hostitele je ve výchozím nastavení zakázáno. Chcete-li povolit middleware, definujte AllowedHosts klíč v appsettings.json / appSettings. <EnvironmentName> . JSON. Hodnota je seznam názvů hostitelů oddělených středníkem bez čísel portů:

appsettings.json:

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

Poznámka

Middleware předávaných hlaviček má také AllowedHosts možnost. Middleware předávaných hlaviček a middleware pro filtrování hostitele mají podobné funkce pro různé scénáře. Nastavení AllowedHosts pomocí předávaných middlewarových hlaviček je vhodné v případě, že Host Hlavička není zachována při předávání požadavků pomocí reverzního proxy server nebo nástroje pro vyrovnávání zatížení. Nastavení AllowedHosts pomocí middlewaru pro filtrování hostitele je vhodné Kestrel , pokud 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í .

Vyprazdňování požadavku HTTP/1.1

Otevírání připojení HTTP je časově náročné. V případě protokolu HTTPS je také náročný na prostředky. Proto se Kestrel pokusí znovu použít připojení podle protokolu HTTP/1.1. Aby bylo možné připojení znovu použít, musí být text žádosti plně spotřebovaný. Aplikace nespotřebovává text žádosti vždycky, například POST žádosti, kde server vrací přesměrování nebo odpověď 404. V POST případě případu přesměrování:

  • Klient již mohl odeslat část POST dat.
  • Server zapisuje odpověď 301.
  • Připojení nelze použít pro novou žádost, dokud nebudou POST data z předchozího textu požadavku plně přečtena.
  • Kestrel pokusí se vyprázdnit tělo žádosti. Vyprázdnit tělo žádosti znamená čtení a zahození dat bez jejich zpracování.

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

  • Vyprázdnění má časový limit pět sekund, což není konfigurovatelné.
  • Pokud nebyla všechna data zadaná v Content-Length Transfer-Encoding hlavičce nebo přečtena před časovým limitem, připojení je zavřeno.

Někdy je možné, že budete chtít žádost ukončit hned nebo po zápisu odpovědi. Například klienti mohou mít omezující data, takže omezení nahraných dat může být prioritou. V takových případech pro ukončení žádosti zavolejte HttpContext. Abort z kontroleru, Razor stránky nebo middlewaru.

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

  • Vytváření nových připojení může být pomalé a nákladné.
  • Není zaručeno, že klient před zavřením připojení přečetl odpověď.
  • Volání Abort by mělo být vzácné a vyhrazené pro závažné chybové případy, ne běžné chyby.
    • Volá se jenom v případě, že je Abort potřeba vyřešit konkrétní problém. Například volejte, Abort Pokud se zlomyslní klienti pokoušejí POST data nebo když dojde k chybě v kódu klienta, která způsobuje velké nebo velké požadavky.
    • Nevolejte Abort pro běžné chybové situace, například HTTP 404 (Nenalezeno).

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

Tento proces se liší od protokolu HTTP/2, protože protokol podporuje přerušování jednotlivých datových proudů požadavků bez ukončení připojení. Nedá se použít 5 sekundový časový limit vyprázdnění. Pokud po dokončení odpovědi dojde k nepřečteným datům textu žádosti, server odešle snímek HTTP/2 RST. Další datové snímky požadavku jsou ignorovány.

Pokud je to možné, je lepší, aby klienti využili hlavičku žádosti očekávat: 100-pokračovat a čekali na odpověď serveru před zahájením odesílání textu žádosti. Díky tomu může klient příležitost před odesláním nepotřebných dat ověřit odpověď a zrušit jejich přerušení.

Další zdroje informací

Kestrelje webový server pro různé platformy pro ASP.NET Core. Kestrelje webový server, který je ve výchozím nastavení součástí ASP.NET Core šablon projektů.

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

  • HTTPS
  • Neprůhledný upgrade používaný k povolení WebSockets
  • Technologie UNIX Sockets s vysokým výkonem za Nginx

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

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

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

Kestreldá se použít samostatně nebo s reverzním proxy server, jako je například Internetová informační služba (IIS), Nginxnebo Apache. Reverzní proxy server přijímá požadavky HTTP ze sítě a přesměruje je na Kestrel .

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

::: No-Loc (Kestrel)::: komunikuje přímo s internetem bez reverzního proxy server

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

::: No-Loc (Kestrel)::: komunikuje nepřímo s internetem prostřednictvím reverzní proxy server, jako je IIS, Nginx nebo Apache.

Buď konfigurace, s zpětným proxy server nebo bez něj, je podporovaná konfigurace hostování.

Kestrel používá se jako hraniční Server bez reverzní proxy server nepodporuje sdílení stejné IP adresy a portu mezi více procesy. Pokud Kestrel je nakonfigurován tak, aby naslouchal na portu, Kestrel zpracovává veškerý provoz tohoto portu bez ohledu na Host hlavičky požadavků. Reverzní proxy server, který může sdílet porty, má možnost přesměrovat požadavky na Kestrel jedinečnou IP adresu a port.

I v případě, že se zpětný proxy server nepožaduje, může být použití reverzní proxy server vhodnou volbou.

Reverzní proxy:

  • Může omezit vystavenou veřejnou plochu v aplikacích, které hostuje.
  • Poskytněte další vrstvu konfigurace a obrany.
  • Může se lépe integrovat se stávající infrastrukturou.
  • Zjednodušte vyrovnávání zatížení a konfiguraci 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.

Upozornění

Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci pro přesměrované hlavičky middleware.

jak používat Kestrel v aplikacích ASP.NET Core

Microsoft. AspNetCore. Server. Kestrel balíček je zahrnutý v Microsoft.AspNetCore.app Metapackage.

ve výchozím nastavení používají šablony projektu ASP.NET Core Kestrel . V programu program. cs volá kód šablony CreateDefaultBuilder , který volá UseKestrel na pozadí.

Chcete-li po volání poskytnout další konfiguraci CreateDefaultBuilder , zavolejte UseKestrel :

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

Další informace o CreateDefaultBuilder a sestavení hostitele naleznete v části Nastavení hostitele v tématu ASP.NET Core Webový hostitel .

Kestrel nastavení

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

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

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

using Microsoft.AspNetCore.Server.Kestrel.Core;

Kestrel Možnosti, které jsou nakonfigurované v kódu jazyka C# v následujících příkladech, lze nastavit také pomocí zprostředkovatele konfigurace. Zprostředkovatel konfigurace souboru může například načíst Kestrel konfiguraci z nebo appsettings.json appsettings.{ Soubor Environment}.json:

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

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

  • Konfigurace Kestrel v Startup.ConfigureServices nástroji :

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

    2. V Startup.ConfigureServices souboru Kestrel načtěte oddíl konfigurace Kestrel do konfigurace nástroje :

      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 souboru Program.cs načtěte Kestrel oddíl konfigurace do konfigurace souboru Kestrel :

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

Oba výše uvedené přístupy fungují s libovolným poskytovatelem konfigurace.

Časový limit pro keep-alive

KeepAliveTimeout

Získá nebo nastaví časový limit udržovat. Výchozí hodnota je 2 minuty.

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

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

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Maximální počet souběžných otevřených připojení TCP je možné nastavit pro celou aplikaci s následujícím kódem:

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

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

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

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ý přístup k přepsání limitu v aplikaci ASP.NET Core MVC je použití atributu RequestSizeLimitAttribute v metodě akce:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

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

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

Přepište nastavení pro konkrétní 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));
    }

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

Pokud aplikace běží mimo proces za modulem ASP.NET Core,je limit velikosti textu požadavku zakázán, protože služba IIS už Kestrel tento limit nastavuje.

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

MinRequestBodyDataRate MinResponseDataRate

Kestrel kontroluje každou sekundu, pokud data přicházejí zadanou rychlostí v bajtech za sekundu. Pokud rychlost klesne pod minimum, dojde k časovému limitu připojení. Období odkladu je doba, která klientovi umožňuje zvýšit frekvenci odesílání až na minimum. Během této doby se tato sazba Kestrel nekontroluje. Období odkladu pomáhá zabránit zahazování připojení, která zpočátku odesílají data pomalou rychlostí kvůli pomalému spuštění protokolu TCP.

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

Minimální sazba platí také pro odpověď. Kód pro nastavení limitu požadavků a limitu odpovědi je stejný s výjimkou kódu nebo v RequestBody Response názvech vlastností a rozhraní.

Tady je příklad, který ukazuje, jak nakonfigurovat minimální přenosovou rychlost v souboru Program.cs:

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

Časový limit 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.

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

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

Upozornění

Velký počet blokující synchronních vstupně-výstupních operací může vést k vyhřešování fondu vláken, což aplikaci přestane reagovat. Tuto možnost AllowSynchronousIO povolte pouze v případě, že používáte knihovnu, která nepodporuje asynchronní V/V operace.

Následující příklad zakáže synchronní vstupně-výstupní operace:

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

Informace o dalších Kestrel možnostech a omezeních najdete v těchto tématu:

Konfigurace koncového bodu

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

  • http://localhost:5000
  • https://localhost:5001 (když je k dispozici místní certifikát pro vývoj)

Adresy URL můžete zadat 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 poskytovaná 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 certifikát pro vývoj:

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

Project konfigurace aplikací tak, aby ve výchozím nastavení běží na HTTPS, a zahrnují přesměrování HTTPS a podporu HSTS.

Voláním Listen metody nebo můžete nakonfigurovat ListenUnixSocket KestrelServerOptions předpony adres URL a porty pro Kestrel .

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

KestrelServerOptions Konfigurace:

ConfigureEndpointDefaults(Action <ListenOptions> )

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

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

Poznámka

U koncových bodů Listen vytvořených voláním ConfigureEndpointDefaults před voláním se nebudou uplatňovat výchozí hodnoty.

ConfigureHttpsDefaults(Akce <HttpsConnectionAdapterOptions> )

Určuje konfiguraci, která Action se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults vícekrát nahradí předchozí Action hodnoty za poslední Action zadané.

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

Poznámka

U koncových bodů Listen vytvořených voláním ConfigureHttpsDefaults před voláním se nebudou uplatňovat výchozí hodnoty.

Configure(IConfiguration)

Vytvoří zavaděč konfigurace pro Kestrel nastavení, které přijímá IConfiguration jako vstup. Konfigurace musí být vymezená konfiguračním oddílem pro Kestrel .

ListenOptions.UseHttps

KestrelNakonfigurujte, aby se protokol HTTPS používat.

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 Action pro konfiguraci HttpsConnectionAdapterOptions . Vrátí 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ě, 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í být poskytnut minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

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

Žádná konfigurace

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

Nahradit výchozí certifikát z konfigurace

CreateDefaultBuilder Při Configure(context.Configuration.GetSection("Kestrel")) načítání konfigurace volá ve výchozím nastavení 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, buď ze souboru na disku, nebo z úložiště certifikátů.

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

  • Nastavte AllowInvalid na true , aby povolovala použití neplatných certifikátů (například certifikátů podepsaných svým držitelem).
  • Libovolný koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v části certifikáty > výchozí 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 zadání certifikátu pomocí polí úložiště certifikátů. Například > výchozí certifikát může být zadán jako:

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

  • V názvech koncových bodů se nerozlišují malá a velká písmena. Například HTTPS a Https jsou platné.
  • UrlU každého koncového bodu je vyžadován parametr. Formát pro tento parametr je stejný jako Urls konfigurační parametr nejvyšší úrovně s tím rozdílem, že je omezen na jedinou hodnotu.
  • Tyto koncové body nahrazují hodnoty definované v konfiguraci nejvyšší úrovně Urls místo jejich přidání do těchto koncových bodů. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní pomocí koncových bodů definovaných v konfiguračním oddílu.
  • CertificateOddíl je nepovinný. Pokud Certificate není oddíl zadaný, použijí se výchozí hodnoty definované v dřívějších scénářích. Pokud nejsou k dispozici žádné výchozí hodnoty, Server vyvolá výjimku a nemůže se spustit.
  • CertificateOddíl podporuje jak heslo cesty – , tak – certifikáty úložiště subjektu.
  • V takovém případě může být definován libovolný počet koncových bodů, pokud to nezpůsobí konflikty portů.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) Vrátí KestrelConfigurationLoader .Endpoint(string name, listenOptions => { }) metodu s metodou, kterou lze použít k doplnění nastavení nakonfigurovaného koncového bodu:
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

KestrelServerOptions.ConfigurationLoader k pokračování v iteraci u stávajícího zavaděče se dá získat přímý odkaz, jako je třeba ten, který poskytuje CreateDefaultBuilder .

  • Konfigurační oddíl pro každý koncový bod je k dispozici na možnostech v Endpoint metodě, aby bylo možné číst vlastní nastavení.
  • Více konfigurací může být načteno voláním options.Configure(context.Configuration.GetSection("{SECTION}")) znovu s jiným oddílem. Je použita pouze poslední konfigurace, pokud Load není explicitně volána při předchozích instancích. Metapackage nevolá Load , aby se jeho výchozí konfigurační oddíl mohl nahradit.
  • KestrelConfigurationLoader zrcadlí Listen rodinu rozhraní API z KestrelServerOptions as Endpoint přetížení, takže koncové body kódu a konfigurace lze konfigurovat 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

ConfigureEndpointDefaults a ConfigureHttpsDefaults dá se použít ke změně výchozího nastavení pro ListenOptions a HttpsConnectionAdapterOptions , včetně přepsání výchozího certifikátu zadaného v předchozím scénáři. ConfigureEndpointDefaults a ConfigureHttpsDefaults měla by být volána před konfigurací koncových bodů.

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

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

Kestrel Podpora pro SNI

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

Kestrel podporuje SNI prostřednictvím ServerCertificateSelector zpětného volání. Zpětné volání je vyvoláno jednou za připojení, které aplikaci umožní 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. V systému net461 nebo novějším je zpětné volání vyvoláno, ale name je vždy null . nameJe také v null případě, že klient v TLS handshake neposkytne parametr názvu hostitele.
  • Všechny weby běží ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu napříč několika instancemi bez reverzního proxy serveru.
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ListenAnyIP(5005, listenOptions =>
            {
                listenOptions.UseHttps(httpsOptions =>
                {
                    var localhostCert = CertificateLoader.LoadFromStoreCert(
                        "localhost", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var exampleCert = CertificateLoader.LoadFromStoreCert(
                        "example.com", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var subExampleCert = CertificateLoader.LoadFromStoreCert(
                        "sub.example.com", "My", StoreLocation.CurrentUser,
                        allowInvalid: true);
                    var certs = new Dictionary<string, X509Certificate2>(
                        StringComparer.OrdinalIgnoreCase);
                    certs["localhost"] = localhostCert;
                    certs["example.com"] = exampleCert;
                    certs["sub.example.com"] = subExampleCert;

                    httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
                    {
                        if (name != null && certs.TryGetValue(name, out var cert))
                        {
                            return cert;
                        }

                        return exampleCert;
                    };
                });
            });
        })
        .Build();

Protokolování připojení

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

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

Vytvoření vazby na soket TCP

ListenMetoda se váže k soketu TCP a pomocí lambda možností povolíte konfiguraci certifikátu X. 509:

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

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

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

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.

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

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

Vytvoření vazby na soket UNIX

Naslouchat na soketu se systémem UNIX ListenUnixSocket , aby se zlepšil výkon pomocí Nginx, jak je znázorněno v tomto příkladu:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testpassword");
            });
        });
  • V souboru Nginx confiuguration nastavte server > location > proxy_pass položku na http://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} je název soketu poskytnutý ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
  • Zajistěte, aby byl soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock ).

Port 0

Když 0 je zadané číslo portu, Kestrel dynamicky se váže k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel 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ž se aplikace spustí, výstup okna konzoly indikuje dynamický port, na který se aplikace dá získat:

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

Omezení

Konfigurace koncových bodů 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é, pokud chcete, aby kód pracoval se servery jiným než Kestrel . Mějte ale na paměti následující omezení:

  • Protokol HTTPS nelze s těmito přístupy použít, pokud není k dispozici výchozí certifikát v konfiguraci koncového bodu HTTPS (například pomocí KestrelServerOptions Konfigurace nebo konfiguračního souboru, jak je uvedeno výše v tomto tématu).
  • Při Listen UseUrls současném použití obou přístupů a Listen koncových bodů se koncové body přepisují UseUrls .

Konfigurace koncového bodu služby IIS

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

Konfigurace přenosu Libuv

s vydáním ASP.NET Core 2,1 se Kestrel výchozí přenos už nepoužívá na Libuv, ale vychází ze spravovaných soketů. jedná se o zásadní změnu pro aplikace ASP.NET Core 2,0 upgradované na 2,1, které volá UseLibuv a závisí na jednom z následujících balíčků:

Pro projekty, které vyžadují použití Libuv:

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

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • Volání UseLibuv :

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

Předpony adresy URL

Při použití UseUrls , --urls argumentu 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 některém z následujících formátů.

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

  • Adresa IPv4 s číslem portu

    http://65.55.39.10:80/
    

    0.0.0.0 je zvláštní případ, který se váže ke všem adresám IPv4.

  • Adresa IPv6 s číslem portu

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

    [::] je ekvivalentem protokolu IPv4 pro protokol IPv6 0.0.0.0 .

  • Název hostitele s číslem portu

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

    Názvy hostitelů, * a + nejsou speciální. Cokoli se nerozpoznalo jako platná IP adresa nebo localhost se váže ke všem IP adresám IPv4 a IPv6. pokud chcete navazovat různé názvy hostitelů na různé ASP.NET Core aplikace na stejném portu, použijte HTTP.sys nebo reverzní proxy server, jako je IIS, Nginx nebo Apache.

    Upozornění

    Hostování v konfiguraci reverzního proxy serveru vyžaduje konfiguraci pro přesměrované hlavičky middleware.

  • localhostNázev hostitele 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í se Kestrel pokusí vytvořit propojení s rozhraními zpětné smyčky IPv4 i IPv6. Pokud je požadovaný port používán jinou službou na rozhraní zpětné smyčky, Kestrel spuštění se nespustí. Pokud je rozhraní zpětné smyčky v žádném jiném případě nedostupné (většinou vzhledem k tomu, že protokol IPv6 není podporovaný), Kestrel zaznamená upozornění.

Filtrování hostitele

I když Kestrel podporuje konfiguraci na základě prefixů http://example.com:5000 , jako je, Kestrel z velké části se název hostitele ignoruje. Hostitel localhost je zvláštní případ, který se používá pro vazbu na adresy zpětné smyčky. Každý hostitel, který je jiný než explicitní IP adresa, se váže na všechny veřejné IP adresy. Host hlavičky nejsou ověřené.

Jako alternativní řešení použijte middleware pro filtrování hostitele. middleware pro filtrování hostitele poskytuje balíček Microsoft. AspNetCore. HostFiltering , který je zahrnutý v Microsoft.AspNetCore.App metapackage (ASP.NET Core 2,1 nebo 2,2). Middleware je přidána pomocí CreateDefaultBuilder , který volá AddHostFiltering :

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

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

Middleware pro filtrování hostitele je ve výchozím nastavení zakázáno. Chcete-li povolit middleware, definujte AllowedHosts klíč v appsettings.json / appSettings. <EnvironmentName> . JSON. Hodnota je seznam názvů hostitelů oddělených středníkem bez čísel portů:

appsettings.json:

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

Poznámka

Middleware předávaných hlaviček má také AllowedHosts možnost. Middleware předávaných hlaviček a middleware pro filtrování hostitele mají podobné funkce pro různé scénáře. Nastavení AllowedHosts pomocí předávaných middlewarových hlaviček je vhodné v případě, že Host Hlavička není zachována při předávání požadavků pomocí reverzního proxy server nebo nástroje pro vyrovnávání zatížení. Nastavení AllowedHosts pomocí middlewaru pro filtrování hostitele je vhodné Kestrel , pokud 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í .

Vyprazdňování požadavku HTTP/1.1

Otevírání připojení HTTP je časově náročné. V případě protokolu HTTPS je také náročný na prostředky. Proto se Kestrel pokusí znovu použít připojení podle protokolu HTTP/1.1. Aby bylo možné připojení znovu použít, musí být text žádosti plně spotřebovaný. Aplikace nespotřebovává text žádosti vždycky, například POST žádosti, kde server vrací přesměrování nebo odpověď 404. V POST případě případu přesměrování:

  • Klient již mohl odeslat část POST dat.
  • Server zapisuje odpověď 301.
  • Připojení nelze použít pro novou žádost, dokud nebudou POST data z předchozího textu požadavku plně přečtena.
  • Kestrel pokusí se vyprázdnit tělo žádosti. Vyprázdnit tělo žádosti znamená čtení a zahození dat bez jejich zpracování.

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

  • Vyprázdnění má časový limit pět sekund, což není konfigurovatelné.
  • Pokud nebyla všechna data zadaná v Content-Length Transfer-Encoding hlavičce nebo přečtena před časovým limitem, připojení je zavřeno.

Někdy je možné, že budete chtít žádost ukončit hned nebo po zápisu odpovědi. Například klienti mohou mít omezující data, takže omezení nahraných dat může být prioritou. V takových případech pro ukončení žádosti zavolejte HttpContext. Abort z kontroleru, Razor stránky nebo middlewaru.

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

  • Vytváření nových připojení může být pomalé a nákladné.
  • Není zaručeno, že klient před zavřením připojení přečetl odpověď.
  • Volání Abort by mělo být vzácné a vyhrazené pro závažné chybové případy, ne běžné chyby.
    • Volá se jenom v případě, že je Abort potřeba vyřešit konkrétní problém. Například volejte, Abort Pokud se zlomyslní klienti pokoušejí POST data nebo když dojde k chybě v kódu klienta, která způsobuje velké nebo velké požadavky.
    • Nevolejte Abort pro běžné chybové situace, například HTTP 404 (Nenalezeno).

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

Tento proces se liší od protokolu HTTP/2, protože protokol podporuje přerušování jednotlivých datových proudů požadavků bez ukončení připojení. Nedá se použít 5 sekundový časový limit vyprázdnění. Pokud po dokončení odpovědi dojde k nepřečteným datům textu žádosti, server odešle snímek HTTP/2 RST. Další datové snímky požadavku jsou ignorovány.

Pokud je to možné, je lepší, aby klienti využili hlavičku žádosti očekávat: 100-pokračovat a čekali na odpověď serveru před zahájením odesílání textu žádosti. Díky tomu může klient příležitost před odesláním nepotřebných dat ověřit odpověď a zrušit jejich přerušení.

Další zdroje informací