Megosztás a következőn keresztül:

Kestrel webkiszolgáló a ASP.NET Core-ban

Jegyzet

Ez nem a cikk legújabb verziója. Az aktuális kiadást ennek a cikknek a .NET 9-es verziójábantalálod.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadást ennek a cikknek a .NET 9-es verziójábantalálod.

Fontos

Ezek az információk egy olyan előzetes termékre vonatkoznak, amelyet a kereskedelmi forgalomba kerülés előtt jelentősen módosíthatnak. A Microsoft nem vállal kifejezett vagy hallgatólagos szavatosságot az itt megadott információkra vonatkozóan.

Az aktuális kiadást ennek a cikknek a .NET 9-es verziójábantalálod.

Tom Dykstra , Chris Rossés Stephen Halter

Kestrel ASP.NET Core platformfüggetlenwebkiszolgálója. Kestrel a ASP.NET Core ajánlott kiszolgálója, és alapértelmezés szerint ASP.NET Core-projektsablonokban van konfigurálva.

Kestrelfunkciói a következők:

  • Platformfüggetlen:Kestrel egy platformfüggetlen webkiszolgáló, amely Windows, Linux és macOS rendszeren fut.
  • Nagy teljesítmény: aKestrel úgy van optimalizálva, hogy nagy számú egyidejű kapcsolatot hatékonyan kezeljen.
  • Egyszerű: Erőforrás-korlátozott környezetekben, például tárolókban és peremeszközökön való futtatáshoz optimalizálva.
  • biztonságosan megerősítve:Kestrel támogatja a HTTPS-t, és erős védelmet nyújt a webkiszolgáló biztonsági rései ellen.
  • Széles protokoll támogatása:Kestrel támogatja a gyakori webes protokollokat, többek között a következőket:
  • Integráció a ASP.NET Core-nal: Zökkenőmentes integráció más ASP.NET Core-összetevőkkel, például a köztes szoftverfolyamattal, a függőséginjektálással és a konfigurációs rendszerrel.
  • rugalmas számítási feladatok: Kestrel számos számítási feladatot támogat:
    • ASP.NET keretrendszerei, mint a Minimal API-k, MVC, Razor oldalak, SignalR, Blazorés gRPC.
    • Fordított proxy létrehozása a YARP segítségével.
  • Bővíthetőség:Kestrel testreszabása konfigurációval, köztes szoftverekkel és egyéni átvitelekkel.
  • Teljesítménydiagnosztika:Kestrel beépített teljesítménydiagnosztikai funkciókat biztosít, például naplózást és metrikákat.

Kezdje el

ASP.NET Alapvető projektsablonok alapértelmezés szerint Kestrel használnak, ha nem IIS-ben üzemeltetik. A következő sablon által létrehozott Program.csesetén a WebApplication.CreateBuilder metódus belül hívja meg a UseKestrel-t.

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

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

app.Run();

A WebApplication és a WebApplicationBuilderkonfigurálásáról további információt a Minimal API-k gyorsreferenciatalál.

Választható ügyféltanúsítványok

Azokról az alkalmazásokról, amelyeknek tanúsítványsal kell védenie az alkalmazás egy részét, olvassa el Választható ügyféltanúsítványokcímű témakört.

Viselkedés hibakereső csatlakoztatásával

A következő időtúllépések és sebességkorlátozások nem lesznek kényszerítve, ha egy hibakereső egy Kestrel folyamathoz van csatolva:

További erőforrások

Jegyzet

A .NET 5-től a Kestrel libuv-átvitele elavult. A libuv-átvitel nem kap frissítéseket az új operációsrendszer-platformok, például a Windows ARM64 támogatásához, és egy későbbi kiadásban el lesz távolítva. Távolítsa el az elavult UseLibuv metódus hívásait, és használja helyette a Kestrelalapértelmezett Socket átvitelt.

Kestrel ASP.NET Core platformfüggetlenwebkiszolgálója. Kestrel az a webkiszolgáló, amely alapértelmezés szerint megtalálható és engedélyezve van ASP.NET Core-projektsablonokban.

Kestrel a következő forgatókönyveket támogatja:

  • HTTPS
  • HTTP/2 (kivéve macOS†)
  • Átlátszatlan frissítés WebSockets engedélyezéséhez
  • Unix socketek az Nginx mögött a nagy teljesítményért

†HTTP/2 egy későbbi kiadásban macOS rendszeren is támogatott lesz.

Kestrel minden olyan platformon és verzióban támogatott, amelyet a .NET Core támogat.

Kezdje el

ASP.NET Alapvető projektsablonok alapértelmezés szerint Kestrel használnak, ha nem IIS-ben üzemeltetik. A következő sablon által létrehozott Program.csesetén a WebApplication.CreateBuilder metódus belül hívja meg a UseKestrel-t.

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

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

app.Run();

A WebApplication és a WebApplicationBuilderkonfigurálásáról további információt a Minimal API-k gyorsreferenciatalál.

Választható ügyféltanúsítványok

Azokról az alkalmazásokról, amelyeknek tanúsítványsal kell védenie az alkalmazás egy részét, olvassa el Választható ügyféltanúsítványokcímű témakört.

Viselkedés hibakereső csatlakoztatásával

A következő időtúllépések és sebességkorlátozások nem lesznek kényszerítve, ha egy hibakereső egy Kestrel folyamathoz van csatolva:

További erőforrások

Jegyzet

A .NET 5-től a Kestrel libuv-átvitele elavult. A libuv-átvitel nem kap frissítéseket az új operációsrendszer-platformok, például a Windows ARM64 támogatásához, és egy későbbi kiadásban el lesz távolítva. Távolítsa el az elavult UseLibuv metódus hívásait, és használja helyette a Kestrelalapértelmezett Socket átvitelt.

Kestrel ASP.NET Core platformfüggetlenwebkiszolgálója. Kestrel az a webkiszolgáló, amely alapértelmezés szerint megtalálható és engedélyezve van ASP.NET Core-projektsablonokban.

Kestrel a következő forgatókönyveket támogatja:

  • HTTPS
  • HTTP/2 (kivéve macOS†)
  • Átlátszatlan frissítés WebSockets engedélyezéséhez
  • Unix socketek az Nginx mögött a nagy teljesítményért

†HTTP/2 egy későbbi kiadásban macOS rendszeren is támogatott lesz.

Kestrel minden olyan platformon és verzióban támogatott, amelyet a .NET Core támogat.

Mintakód megtekintése vagy letöltése (letöltése)

Kezdje el

ASP.NET Alapvető projektsablonok alapértelmezés szerint Kestrel használnak, ha nem IIS-ben üzemeltetik. A Program.csConfigureWebHostDefaults metódus meghívja 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>();
        });

A gazdagép létrehozásáról szóló további információkért lásd a Gazdagép beállítása és Alapértelmezett készítői beállításai szakaszait .NET Generic Host az ASP.NET Core-ben.

Választható ügyféltanúsítványok

Azokról az alkalmazásokról, amelyeknek tanúsítványsal kell védenie az alkalmazás egy részét, olvassa el Választható ügyféltanúsítványokcímű témakört.

További erőforrások

Jegyzet

A .NET 5-től a Kestrel libuv-átvitele elavult. A libuv-átvitel nem kap frissítéseket az új operációsrendszer-platformok, például a Windows ARM64 támogatásához, és egy későbbi kiadásban el lesz távolítva. Távolítsa el az elavult UseLibuv metódus hívásait, és használja helyette a Kestrelalapértelmezett Socket átvitelt.

Kestrel ASP.NET Core platformfüggetlenwebkiszolgálója. Kestrel az a webkiszolgáló, amely alapértelmezés szerint szerepel ASP.NET Core-projektsablonokban.

Kestrel a következő forgatókönyveket támogatja:

  • HTTPS
  • Átlátszatlan frissítés WebSockets engedélyezéséhez
  • Unix socketek az Nginx mögött a nagy teljesítményért
  • HTTP/2 (kivéve macOS†)

†HTTP/2 egy későbbi kiadásban macOS rendszeren is támogatott lesz.

Kestrel minden olyan platformon és verzióban támogatott, amelyet a .NET Core támogat.

Mintakód megtekintése vagy letöltése (letöltése)

HTTP/2-támogatás

HTTP/2 ASP.NET Core-alkalmazásokhoz érhető el, ha az alábbi alapkövetelmények teljesülnek:

  • Operációs rendszer†
    • Windows Server 2016/Windows 10 vagy újabb‡
    • Linux OpenSSL 1.0.2 vagy újabb verzióval (például Ubuntu 16.04 vagy újabb)
  • Cél keretrendszer: .NET Core 2.2 vagy újabb
  • Application-Layer protokolltárgyalás (ALPN) kapcsolat
  • TLS 1.2 vagy újabb kapcsolat

†HTTP/2 egy későbbi kiadásban macOS rendszeren is támogatott lesz. ‡Kestrel korlátozottan támogatja a HTTP/2-t Windows Server 2012 R2 és Windows 8.1 rendszeren. A támogatás korlátozott, mert az ezeken az operációs rendszereken elérhető támogatott TLS-titkosítási csomagok listája korlátozott. A TLS-kapcsolatok védelméhez szükség lehet egy három pontból álló digitális aláírási algoritmussal (ECDSA) létrehozott tanúsítványra.

HTTP/2-kapcsolat létesítése esetén HttpRequest.Protocol jelent HTTP/2.

A .NET Core 3.0-tól kezdve a HTTP/2 alapértelmezés szerint engedélyezve van. A konfigurációval kapcsolatos további információkért tekintse meg a Kestrel és ListenOptions.Protocols szakaszokat.

Mikor érdemes fordított proxyval használni Kestrel?

A(z) Kestrel önmagában is használható, vagy a(z) fordított proxykiszolgálóval. A fordított proxykiszolgáló HTTP-kéréseket fogad a hálózatról, és továbbítja őket Kestrel. A fordított proxykiszolgálók például a következők:

Kestrel peremhálózati (internetkapcsolattal rendelkező) webkiszolgálóként használják:

Kestrel közvetlenül kommunikál az internettel a reverse proxy szerver nélkül

fordított proxykonfigurációban használt Kestrel:

Kestrel közvetve kommunikál az internettel fordított proxykiszolgálón keresztül, például IIS, Nginx vagy Apache

A fordított proxykiszolgálóval vagy anélkül végzett konfiguráció egy támogatott üzemeltetési konfiguráció.

Kestrel fordított proxykiszolgáló nélküli peremhálózati kiszolgálóként nem támogatja ugyanazt az IP-címet és portot több folyamat között. Ha Kestrel egy port figyelésére van konfigurálva, Kestrel a kérések Host fejlécétől függetlenül kezeli az adott port összes forgalmát. A portok megosztására alkalmas fordított proxyk egyedi IP-címen és porton továbbíthatják a kéréseket Kestrel.

Még ha nincs is szükség fordított proxykiszolgálóra, a fordított proxykiszolgáló használata jó választás lehet.

Fordított proxy:

  • Korlátozhatja az általa üzemeltetett alkalmazások nyilvános felületét.
  • További konfigurációs és mélységi kiberbiztonsági réteg biztosítása.
  • Jobban integrálható a meglévő infrastruktúrával.
  • Egyszerűsítse a terheléselosztást és a biztonságos kommunikációt (HTTPS). Csak a fordított proxykiszolgálóhoz van szükség X.509-tanúsítványra, és a kiszolgáló egyszerű HTTP használatával tud kommunikálni az alkalmazás kiszolgálóival a belső hálózaton.

Figyelmeztetés

A fordított proxykonfigurációban való üzemeltetéshez Továbbított fejlécek Köztes szoftver konfigurációsszükséges.

Kestrel ASP.NET Core-alkalmazásokban

ASP.NET Core-projektsablonok alapértelmezés szerint Kestrel használnak. A Program.csConfigureWebHostDefaults metódus meghívja 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>();
        });

A gazdagép létrehozásáról szóló további információkért lásd a Gazdagép beállítása és Alapértelmezett készítői beállításai szakaszait .NET Generic Host az ASP.NET Core-ben.

Ha további konfigurációt szeretne megadni ConfigureWebHostDefaultshívása után, használja a 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 beállítások

A Kestrel webkiszolgáló kényszerkonfigurációs lehetőségekkel rendelkezik, amelyek különösen hasznosak az internetes környezetekben.

Állítson be korlátozásokat a Limits osztály KestrelServerOptions tulajdonságára. A Limits tulajdonság a KestrelServerLimits osztály egy példányát tartalmazza.

Az alábbi példák a Microsoft.AspNetCore.Server.Kestrel.Core névteret használják:

using Microsoft.AspNetCore.Server.Kestrel.Core;

A cikk későbbi részében látható példákban Kestrel beállítások C#-kódban vannak konfigurálva. Kestrel beállításokat a konfigurációszolgáltatósegítségével is be lehet állítani. A fájlkonfigurációs szolgáltató például betölthet Kestrel konfigurációt egy appsettings.json vagy appsettings.{Environment}.json fájlból:

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

Jegyzet

KestrelServerOptions és végpontkonfigurációk konfigurálhatók konfigurációszolgáltatók által. A fennmaradó Kestrel konfigurációt C#-kódban kell konfigurálni.

Használja az alábbi módszerek egyikét:

  • Kestrel konfigurálása Startup.ConfigureServices:

    1. Szúrja be a IConfiguration egy példányát a Startup osztályba. Az alábbi példa feltételezi, hogy az injektált konfiguráció hozzá van rendelve a Configuration tulajdonsághoz.

    2. Töltsd be a Startup.ConfigureServices-ban a konfiguráció Kestrel szakaszát a Kestrelkonfigurációjába.

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

  • Konfigurálja a Kestrel-t a gazdagép felépítésekor.

    Töltsd be a Program.cs-ban a konfiguráció Kestrel szakaszát a Kestrelkonfigurációjába.

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

A fenti megközelítések mindkét esetben bármely konfigurációszolgáltatóvalműködnek.

Életbentartási időkorlát

KeepAliveTimeout

Lekéri vagy beállítja az életben tartási időkorlátot. Alapértelmezés szerint 2 perc.

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

Ügyfélkapcsolatok maximális száma

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Az egyidejűleg megnyitott TCP-kapcsolatok maximális száma a teljes alkalmazáshoz beállítható az alábbi kóddal:

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

A HTTP-ről vagy a HTTPS-ről egy másik protokollra (például WebSockets-kérelmekre) frissített kapcsolatokra külön korlát vonatkozik. A kapcsolat frissítése után a rendszer nem számít bele a MaxConcurrentConnections korlátba.

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

A kapcsolatok maximális száma alapértelmezés szerint korlátlan (null).

Kérelem törzsének maximális mérete

MaxRequestBodySize

A kérelem törzsének alapértelmezett maximális mérete 30 000 000 bájt, ami körülbelül 28,6 MB.

A ASP.NET Core MVC-alkalmazások korlátjának felülbírálására javasolt módszer a RequestSizeLimitAttribute attribútum használata műveletmetóduson:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Íme egy példa, amely bemutatja, hogyan konfigurálhatja az alkalmazás korlátozását minden kéréshez:

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

Felülbírálja egy adott kérelem beállítását a köztes szoftverben:

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

Kivétel akkor történik, ha az alkalmazás konfigurálja a kérelem korlátját, miután az alkalmazás megkezdte a kérés olvasását. Van egy IsReadOnly tulajdonság, amely azt jelzi, hogy a MaxRequestBodySize tulajdonság írásvédett állapotban van-e, ami azt jelenti, hogy túl késő a korlát konfigurálásához.

Ha egy alkalmazás folyamaton kívüli fut a ASP.NET core modulmögött, Kestrelkérés törzsméretkorlátja le van tiltva, mert az IIS már beállítja a korlátot.

A kérés törzsének minimális adatsebessége

MinRequestBodyDataRate MinResponseDataRate

Kestrel másodpercenként ellenőrzi, hogy az adatok a megadott bájt/másodperc sebességgel érkeznek-e. Ha a ráta a minimális érték alá csökken, a kapcsolat időtúllépéssel megszakad. A türelmi időszak az az időtartam, amelyet Kestrel biztosít az ügyfélnek, hogy a küldési sebességét megemelje a minimálisra; ez idő alatt a ráta nincs ellenőrizve. A türelmi időszak segít elkerülni azokat a kapcsolatokat, amelyek kezdetben lassú sebességgel küldenek adatokat a TCP lassú indítása miatt.

Az alapértelmezett minimális sebesség 240 bájt/másodperc, 5 másodperces türelmi idővel.

A válaszra egy minimális díj is vonatkozik. A kérelemkorlátot és a válaszkorlátot megadó kód ugyanaz, eltekintve attól, hogy RequestBody vagy Response szerepel a tulajdonság- és interfésznevekben.

Íme egy példa, amely bemutatja, hogyan konfigurálhatók a minimális adatátviteli sebességek Program.cs-ban.

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

Felülbírálja a kérelemenkénti minimális díjkorlátokat a köztes szoftverben:

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

Az előző mintában hivatkozott IHttpMinResponseDataRateFeature nem szerepel a HTTP/2-kérelmek HttpContext.Features, mert a http/2 esetében általában nem támogatott a kérelemalapú sebességkorlátok módosítása, mivel a protokoll támogatja a kérelmek multiplexálását. A IHttpMinRequestBodyDataRateFeature azonban továbbra is HttpContext.Features a HTTP/2-kérésekhez, mivel az olvasási sebességkorlát továbbra is le tiltható teljes egészében kérésenként, ha IHttpMinRequestBodyDataRateFeature.MinDataRatenull egy HTTP/2-kérés esetében is. Kísérlet a IHttpMinRequestBodyDataRateFeature.MinDataRate olvasására vagy annak bármi másra állítására, mint null, egy NotSupportedException kivételt eredményez egy HTTP/2 kérés esetén.

A KestrelServerOptions.Limits konfigurált kiszolgálószintű sebességkorlátozások továbbra is érvényesek a HTTP/1.x és a HTTP/2 kapcsolatokra.

Fejléckérések időtúllépése

RequestHeadersTimeout

Lekéri vagy beállítja, hogy a kiszolgáló mennyi időt tölt a kérésfejlécek fogadásával. Alapértelmezés szerint 30 másodperc.

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

Streamek maximális száma kapcsolatonként

Http2.MaxStreamsPerConnection http/2-kapcsolatonként korlátozza az egyidejű kérésfolyamok számát. A felesleges streameket elutasítjuk.

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

Az alapértelmezett érték 100.

Fejléctábla mérete

A HPACK dekóder kibontja a HTTP/2 kapcsolatok HTTP-fejléceit. Http2.HeaderTableSize korlátozza a HPACK dekóder által használt fejléctömörítési táblázat méretét. Az érték oktettben van megadva, és nullánál nagyobbnak (0) kell lennie.

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

Az alapértelmezett érték 4096.

Keret maximális mérete

Http2.MaxFrameSize a kiszolgáló által fogadott vagy küldött HTTP/2 kapcsolatkeret maximális megengedett méretét jelzi. Az érték oktettben van megadva, és 2^14 (16 384) és 2^24-1 (16 777 215) között kell lennie.

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

Az alapértelmezett érték 2^14 (16 384).

Kérelem fejlécének maximális mérete

Http2.MaxRequestHeaderFieldSize a kérelemfejlécértékek oktettjeiben megengedett maximális méretet jelzi. Ez a korlát a tömörített és tömörítetlen ábrázolásokban lévő névre és értékre is vonatkozik. Az értéknek nullánál (0) nagyobbnak kell lennie.

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

Az alapértelmezett érték 8192.

Kezdeti kapcsolatablak mérete

Http2.InitialConnectionWindowSize jelzi a maximálisan egyszerre pufferelt kérelemtörzsadatok mennyiségét bájtban, összesítve minden kapcsolaton keresztül minden kérelem (folyam) esetében. A kérelmeket a Http2.InitialStreamWindowSizeis korlátozza. Az értéknek nagyobbnak vagy egyenlőnek kell lennie, mint 65 535, és kisebbnek kell lennie, mint 2^31 (2 147 483 648).

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

Az alapértelmezett érték 128 KB (131 072).

Kezdeti streamablak mérete

Http2.InitialStreamWindowSize a kérelem törzsének maximális adatmennyiségét jelzi a kiszolgáló puffereinek bájtban, kérésenként (streamenként) egyszerre. A kérelmeket a Http2.InitialConnectionWindowSizeis korlátozza. Az értéknek nagyobbnak vagy egyenlőnek kell lennie, mint 65 535, és kisebbnek kell lennie, mint 2^31 (2 147 483 648).

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

Az alapértelmezett érték 96 KB (98 304).

Előzetesek

A HTTP-záró fejlécek hasonlóak a HTTP-fejlécekhez, azzal a különbséggel, hogy a válasz törzsének elküldése után küldik őket. Az IIS és a HTTP.sysesetében csak a HTTP/2 válasz trailer támogatott.

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

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

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

Az előző példakódban:

  • SupportsTrailers biztosítja, hogy a pótkocsik támogatottak legyenek a válaszhoz.
  • DeclareTrailer hozzáadja a megadott pótkocsinevet a Trailer válaszfejléchez. A válasz trailer mezőinek deklarálása nem kötelező, de ajánlott. Ha DeclareTrailer van meghívva, annak a válaszfejlécek elküldése előtt kell lennie.
  • AppendTrailer hozzáfűzi a pótkocsit.

Visszaállítás

Az alaphelyzetbe állítás lehetővé teszi, hogy a kiszolgáló visszaállítsa a HTTP/2 kérést egy megadott hibakóddal. Az alaphelyzetbe állítás kérését megszakítottnak tekintjük.

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

Reset az előző kód példában a INTERNAL_ERROR hibakódot adja meg. A HTTP/2 hibakódokkal kapcsolatos további információkért tekintse meg a HTTP/2 specifikáció hibakódjánakszakaszát.

Szinkron be-/kimenet

AllowSynchronousIO szabályozza, hogy engedélyezve van-e a szinkron I/O a kéréshez és a válaszhoz. Az alapértelmezett érték a false.

Figyelmeztetés

A nagyszámú blokkoló szinkron I/O-művelet szálkészlet-kimerüléshez vezethet, ami miatt az alkalmazás válaszképtelenné válik. Csak akkor engedélyezze a AllowSynchronousIO, ha olyan kódtárat használ, amely nem támogatja az aszinkron I/O-t.

Az alábbi példa lehetővé teszi a szinkron I/O-t:

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

További információ az egyéb Kestrel lehetőségekről és korlátokról:

Végpontkonfiguráció

Alapértelmezés szerint ASP.NET Core a következőhöz kötődik:

  • http://localhost:5000
  • https://localhost:5001 (helyi fejlesztési tanúsítvány esetén)

Adja meg az URL-címeket a következővel:

  • ASPNETCORE_URLS környezeti változó.
  • --urls parancssori argumentum.
  • urls gazdagép konfigurációs kulcs.
  • UseUrls bővítménymetódus.

Az e megközelítések használatával megadott érték lehet egy vagy több HTTP- és HTTPS-végpont (HTTPS, ha van alapértelmezett tanúsítvány). Konfigurálja az értéket pontosvesszővel tagolt listaként (például "Urls": "http://localhost:8000;http://localhost:8001").

További információért ezekkel a megközelítésekkel kapcsolatban lásd a szervercímek és a konfiguráció felülbírálásarészt.

Létrejön egy fejlesztési tanúsítvány:

Egyes böngészők explicit engedélyt igényelnek a helyi fejlesztési tanúsítvány megbízhatóságához.

A projektsablonok alapértelmezés szerint HTTPS-alapú futtatásra konfigurálják az alkalmazásokat, és tartalmazzák HTTPS-átirányítást és a HSTS-támogatást.

Hívja meg a(z) Listen-n a ListenUnixSocket vagy a KestrelServerOptions metódust az URL előtagok és portok konfigurálásához Kestrelszámára.

UseUrls, a --urls parancssori argumentum, urls gazdagép konfigurációs kulcsa és a ASPNETCORE_URLS környezeti változó szintén működik, de a jelen szakaszban később feljegyzett korlátozásokkal rendelkezik (a HTTPS-végpont konfigurációja esetén egy alapértelmezett tanúsítványnak kell rendelkezésre állnia).

KestrelServerOptions konfiguráció:

Állítsa be az alapértelmezett végpontokat (Action<ListenOptions>)

Meghatározza a Action konfigurációt, amelyet minden meghatározott végponton futtatni kell. A ConfigureEndpointDefaults többszöri hívása lecseréli a korábbi Action-eket az utolsó megadott Action-re.

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

Jegyzet

A Listenáltal létrehozott végpontok, amelyekre a hívás előtt a ConfigureEndpointDefaults nem vonatkozik, nem alkalmazzák az alapértelmezett értékeket.

HttpsDefaults konfigurálása (HttpsConnectionAdapterOptions< művelet>)

Megad egy Action konfigurációt, amelyet minden egyes HTTPS-végpont számára kell futtatni. A ConfigureHttpsDefaults többszöri hívása lecseréli a korábbi Action-eket az utolsó megadott Action-re.

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

Jegyzet

A Listenáltal létrehozott végpontok, amelyekre a hívás előtt a ConfigureHttpsDefaults nem vonatkozik, nem alkalmazzák az alapértelmezett értékeket.

Konfigurálás(IConfiguration)

Létrehoz egy konfigurációs betöltőt az Kestrel beállításának elvégzéséhez, amely bemenetként egy IConfiguration-et vesz igénybe. A konfigurációt a Kestrelkonfigurációs szakaszára kell korlátozni.

ListenOptions.UseHttps (HTTPS-használat hallgatási beállítások)

Konfigurálja a Kestrel HTTPS használatára.

ListenOptions.UseHttps bővítmények:

  • UseHttps: Konfigurálja a Kestrel, hogy https-t használjon az alapértelmezett tanúsítvánnyal. Kivételt eredményez, ha nincs alapértelmezett tanúsítvány konfigurálva.
  • 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 paraméterek:

  • filename egy tanúsítványfájl elérési útja és fájlneve az alkalmazás tartalomfájljait tartalmazó könyvtárhoz viszonyítva.
  • password az X.509-tanúsítványadatok eléréséhez szükséges jelszó.
  • configureOptions egy Actionkonfigurálására szolgáló HttpsConnectionAdapterOptions. "ListenOptions-at adja vissza."
  • A storeName tanúsítványtár, amelyből a tanúsítványt be kell tölteni.
  • subject a tanúsítvány tulajdonosának neve.
  • allowInvalid jelzi, hogy érvénytelen tanúsítványokat kell-e figyelembe venni, például önaláírt tanúsítványokat.
  • A location a bolthely, ahonnan a tanúsítvány betöltésre kerül.
  • serverCertificate az X.509-tanúsítvány.

Éles környezetben a HTTPS-t explicit módon kell konfigurálni. Legalább egy alapértelmezett tanúsítványt kell megadni.

A következőkben ismertetett támogatott konfigurációk:

  • Nincs konfiguráció
  • Az alapértelmezett tanúsítvány cseréje a konfigurációból
  • Az alapértelmezett értékek módosítása a kódban

Nincs konfiguráció

Kestrel figyeli http://localhost:5000 és https://localhost:5001 (ha van alapértelmezett tanúsítvány).

Az alapértelmezett tanúsítvány cseréje a konfigurációból

CreateDefaultBuilder alapértelmezés szerint meghívja Configure(context.Configuration.GetSection("Kestrel"))Kestrel konfiguráció betöltéséhez. Az alapértelmezett HTTPS alkalmazásbeállításainak konfigurációs sémája Kestrelérhető el. Konfiguráljon több végpontot, köztük az URL-címeket és a használni kívánt tanúsítványokat egy lemezen lévő fájlból vagy egy tanúsítványtárolóból.

Az alábbi appsettings.json példában:

  • Állítsa AllowInvalidtrue értékre az érvénytelen tanúsítványok (például önaláírt tanúsítványok) használatának engedélyezéséhez.
  • Minden olyan HTTPS-végpont, amely nem ad meg tanúsítványt (HttpsDefaultCert a következő példában) a Tanúsítványok>Alapértelmezett vagy a fejlesztési tanúsítvány alatt meghatározott tanúsítványra kerül vissza.
{
  "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>"
      }
    }
  }
}

A Elérési út és a Jelszó helyett bármely tanúsítványcsomóponthoz alternatívaként megadhatja a tanúsítványt a tanúsítványtár mezőinek használatával. A Tanúsítványok>Alapértelmezett tanúsítvány például a következőként adható meg:

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

Sémajegyzetek:

  • A végpontok neve nem érzékeny a kis- és nagybetűkre. Például HTTPS és Https érvényesek.
  • A Url paraméter minden végponthoz szükséges. A paraméter formátuma megegyezik a legfelső szintű Urls konfigurációs paraméterével, azzal a kivételrel, hogy egyetlen értékre van korlátozva.
  • Ezek a végpontok a felső szintű Urls konfigurációban definiált végpontokat helyettesítik ahelyett, hogy hozzáadják őket. A kódban Listen keresztül definiált végpontok a konfigurációs szakaszban meghatározott végpontokkal együtt halmozódnak.
  • A Certificate szakasz nem kötelező. Ha a Certificate szakasz nincs megadva, a rendszer a korábbi forgatókönyvekben definiált alapértelmezett értékeket használja. Ha nem érhetők el alapértelmezett értékek, a kiszolgáló kivételt jelez, és nem indul el.
  • A Certificate szakasz Elérési út–Jelszó és Tárgy–Tároló tanúsítványokat is támogatja.
  • Ilyen módon tetszőleges számú végpont definiálható, amennyiben nem okoznak portütközéseket.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) egy KestrelConfigurationLoader metódussal rendelkező .Endpoint(string name, listenOptions => { }) ad vissza, amely egy konfigurált végpont beállításainak kiegészítésére használható:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader közvetlenül elérhető a meglévő rakodón való iterálás folytatásához, például a CreateDefaultBuilderáltal biztosított.

  • Az egyes végpontok konfigurációs szakasza a Endpoint metódus beállításai között érhető el, hogy az egyéni beállítások olvashatók legyenek.
  • Előfordulhat, hogy több konfiguráció is betöltődik, ha ismét meghívja options.Configure(context.Configuration.GetSection("{SECTION}")) egy másik szakaszsal. Csak az utolsó konfigurációt használja a rendszer, kivéve, ha Load-t explicit módon meghívják a korábbi példányokban. A metacsomag nem hívja meg Load, hogy az alapértelmezett konfigurációs szakasz lecserélhető legyen.
  • KestrelConfigurationLoader a Listen API-családnak a KestrelServerOptionsEndpoint overload funkcióit tükrözi, így a kód- és konfigurációvégpontok ugyanabban a helyben konfigurálhatók. Ezek a túlterhelések nem használnak neveket, és csak a konfiguráció alapértelmezett beállításait használják.

A kód alapértelmezett értékének módosítása

ConfigureEndpointDefaults és ConfigureHttpsDefaults az ListenOptions és a HttpsConnectionAdapterOptionsalapértelmezett beállításainak módosítására használható, beleértve az előző forgatókönyvben megadott alapértelmezett tanúsítvány felülírását is. A végpontok konfigurálása előtt ConfigureEndpointDefaults és ConfigureHttpsDefaults kell meghívni.

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

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

Kestrel SNI- támogatása

kiszolgálónév-jelzés (SNI) több tartomány üzemeltetésére is használható ugyanazon az IP-címen és porton. Az SNI működéséhez az ügyfél elküldi a biztonságos munkamenet állomásnevét a kiszolgálónak a TLS-kézfogás során, hogy a kiszolgáló a megfelelő tanúsítványt tudja biztosítani. Az ügyfél a mellékelt tanúsítványt használja a kiszolgálóval való titkosított kommunikációhoz a TLS-kézfogást követő biztonságos munkamenet során.

Kestrel támogatja az SNI-t a ServerCertificateSelector visszahívási funkcióval. A visszahívást kapcsolatonként egyszer hívjuk meg, hogy az alkalmazás megvizsgálhassa a gazdagép nevét, és kiválaszthassa a megfelelő tanúsítványt.

Az SNI-támogatáshoz a következőre van szükség:

  • A célkeretrendszer netcoreapp2.1 vagy annál újabb verzióján fut. A visszahívás net461 vagy újabb rendszeren hívódik meg, de a name mindig null. A name akkor is null, ha az ügyfél nem adja meg a hosztnév paramétert a TLS kapcsolatfelvétel során.
  • Minden webhely ugyanazon a Kestrel példányon fut. Kestrel nem támogatja az IP-cím és a port megosztását több példány között fordított proxy (reverse proxy) nélkül.
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;
            };
        });
    });
});

Kapcsolatnaplózás

Hívja meg UseConnectionLogging, hogy hibakeresési szintű naplókat bocsátjon ki egy kapcsolat bájtszintű kommunikációjához. A kapcsolatnaplózás hasznos az alacsony szintű kommunikációval kapcsolatos problémák elhárításához, például a TLS titkosítása és a proxyk mögött. Ha UseConnectionLoggingUseHttpselé kerül, a rendszer titkosított forgalmat naplóz. Ha UseConnectionLoggingUseHttpsután kerül, a rendszer naplózza a visszafejtett forgalmat.

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

Hozzákapcsolódás TCP-csatlakozóhoz

A Listen metódus egy TCP-szoftvercsatornához kapcsolódik, és egy beállítási lambda engedélyezi az X.509-tanúsítványkonfigurációt:

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

A példa a ListenOptionsvégpont HTTPS-konfigurációját mutatja be. Ugyanezzel az API-val konfigurálhat más Kestrel beállításokat adott végpontokhoz.

Windows rendszeren az önaláírt tanúsítványok a New-SelfSignedCertificate PowerShell-parancsmaghasználatával hozhatók létre. Lásd a nem támogatott példát: UpdateIISExpressSSLForChrome.ps1.

MacOS, Linux és Windows rendszeren a tanúsítványok OpenSSLhasználatával hozhatók létre.

Kötés Unix-szoftvercsatornához

Az Nginx használatával figyeljen egy Unix socketre ListenUnixSocket a jobb teljesítmény érdekében, ahogy az ebben a példában látható:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • Az Nginx konfigurációs fájlban állítsa a server>location>proxy_pass bejegyzést http://unix:/tmp/{KESTREL SOCKET}:/;értékre. {KESTREL SOCKET} a ListenUnixSocket számára biztosított foglalat neve (például az előző példában kestrel-test.sock).
  • Győződjön meg arról, hogy a foglalat írásra alkalmas az Nginx számára (például chmod go+w /tmp/kestrel-test.sock).

0. port

Ha a portszám 0 van megadva, Kestrel dinamikusan kapcsolódik egy elérhető porthoz. Az alábbi példa bemutatja, hogyan állapítható meg futásidőben, hogy melyik porthoz van ténylegesen hozzárendelve a Kestrel.

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

Az alkalmazás futtatásakor a konzolablak kimenete azt a dinamikus portot jelzi, ahol az alkalmazás elérhető:

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

Korlátozások

A végpontok konfigurálása a következő módszerekkel:

  • UseUrls
  • --urls parancssori argumentum
  • gazdagép konfigurációs kulcs urls
  • ASPNETCORE_URLS környezeti változó

Ezek a módszerek a Kestrelkívüli kiszolgálókon való kódmunkához hasznosak. Vegye figyelembe azonban a következő korlátozásokat:

  • A HTTPS csak akkor használható ezekkel a módszerekkel, ha a HTTPS-végpont konfigurációjában egy alapértelmezett tanúsítvány van megadva (például KestrelServerOptions konfiguráció vagy konfigurációs fájl használata a jelen témakör korábbi részében látható módon).
  • A Listen és a UseUrls megközelítés egyidejű használata esetén a Listen végpontok felülbírálják a UseUrls végpontokat.

IIS-végpont konfigurálása

Az IIS használatakor az IIS felülbírálási kötéseinek URL-kötéseit Listen vagy UseUrlsállítja be. További információ: ASP.NET Core Module témakör.

FigyelésiBeállítások.Protokollok

A Protocols tulajdonság létrehozza a kapcsolati végponton vagy a kiszolgálón engedélyezett HTTP-protokollokat (HttpProtocols). Rendeljen hozzá egy értéket a Protocols tulajdonsághoz a HttpProtocols enumerációból.

HttpProtocols számérték Engedélyezett kapcsolati protokoll
Http1 Csak HTTP/1.1. TLS-sel vagy anélkül is használható.
Http2 Csak HTTP/2. TLS nélkül csak akkor használható, ha az ügyfél támogatja a Korábbi tudás mód.
Http1AndHttp2 HTTP/1.1 és HTTP/2. A HTTP/2 megköveteli, hogy az ügyfél a HTTP/2-t válassza ki a TLS Application-Layer protokolltárgyalás (ALPN) kézfogás során; ellenkező esetben a kapcsolat alapértelmezés szerint a HTTP/1.1 lesz.

A végpontok alapértelmezett ListenOptions.Protocols értéke HttpProtocols.Http1AndHttp2.

TLS-korlátozások HTTP/2-hez:

  • TLS 1.2-es vagy újabb verzió
  • Az újratárgyalás le van tiltva
  • Tömörítés letiltva
  • Rövid élettartamú kulcscsere minimális méretei:
    • Elliptikus görbe Diffie-Hellman (ECDHE) [RFC4492]: legalább 224 bit
    • Véges mező Diffie-Hellman (DHE) [TLS12]: legalább 2048 bit
  • A titkosítási csomag nem tiltott.

A [TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256] TLS-ECDHE alapértelmezés szerint támogatott a P-256 elliptikus görbével [FIPS186].

Az alábbi példa HTTP/1.1 és HTTP/2 kapcsolatokat engedélyez a 8000-s porton. A kapcsolatokat a TLS egy megadott tanúsítvánnyal védi:

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

A Connection Middleware használatával kapcsolatonként szűrheti a TLS-kézfogásokat adott rejtjelek esetében, ha szükséges.

Az alábbi példa NotSupportedException hibát dob minden olyan titkosítási algoritmus esetén, amelyet az alkalmazás nem támogat. Másik lehetőségként definiálhatja és összehasonlíthatja ITlsHandshakeFeature.CipherAlgorithm az elfogadható titkosítási csomagok listájával.

Nem használ titkosítást CipherAlgorithmType.Null titkosítási algoritmussal.

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

A kapcsolatszűrés egy IConnectionBuilder lambdán keresztül is konfigurálható:

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

Linuxon CipherSuitesPolicy használható a TLS-kézfogások kapcsolatonkénti szűrésére:

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

Protokoll beállítása a konfiguráció alapján

CreateDefaultBuilder alapértelmezés szerint meghívja serverOptions.Configure(context.Configuration.GetSection("Kestrel"))Kestrel konfiguráció betöltéséhez.

Az alábbi appsettings.json példa a HTTP/1.1 protokollt hozza létre az összes végpont alapértelmezett kapcsolati protokolljaként:

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

Az alábbi appsettings.json példa a HTTP/1.1 kapcsolati protokollt hozza létre egy adott végponthoz:

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

A konfiguráció által beállított kód felülbírálási értékekben megadott protokollok.

URL-előtagok

Ha UseUrls, --urls parancssori argumentumot, urls gazdagép konfigurációs kulcsát vagy ASPNETCORE_URLS környezeti változót használ, az URL-előtagok az alábbi formátumok bármelyikében lehetnek.

Csak a HTTP URL-előtagok érvényesek. Kestrel nem támogatja a HTTPS-t az URL-kötések UseUrlshasználatával történő konfigurálásakor.

  • IPv4-cím portszámmal

    http://65.55.39.10:80/

    0.0.0.0 egy speciális eset, amely az összes IPv4-címhez kötődik.

  • IPv6-cím portszámmal

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

    [::] az IPv4 0.0.0.0IPv6-megfelelője.

  • Hosztnév portszámmal

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

    A hosztnevek, *és +, nem különlegesek. Azokat, amelyeket nem ismernek fel érvényes IP-címként, vagy a localhost-t, minden IPv4- és IPv6-IP-címhez kötik. Ha különböző gazdagépneveket szeretne különböző ASP.NET Core-alkalmazásokhoz kötni ugyanazon a porton, használjon HTTP.sys vagy fordított proxykiszolgálót, például IIS, Nginx vagy Apache.

    Figyelmeztetés

    A fordított proxykonfigurációban való üzemeltetéshez Továbbított fejlécek Köztes szoftver konfigurációsszükséges.

  • Gazdagép localhost neve portszámmal vagy visszacsatolási IP-cím portszámmal

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

    Ha localhost van megadva, Kestrel IPv4- és IPv6-visszacsatolási felületekhez is megpróbál csatlakozni. Ha a kért portot egy másik szolgáltatás használja bármelyik visszacsatolási felületen, Kestrel nem indul el. Ha bármelyik visszacsatolási felület más okból nem érhető el (leggyakrabban azért, mert az IPv6 nem támogatott), Kestrel figyelmeztetést naplóz.

Hosztszűrés

Bár a Kestrel támogatja az olyan előtagokon alapuló konfigurációt, mint a http://example.com:5000, a Kestrel nagyrészt figyelmen kívül hagyja a gazdagép nevét. A gazdagép localhost egy speciális eset, amelyet a visszacsatolási címekhez való kötéshez használnak. Az explicit IP-cím kivételével minden gazdagép az összes nyilvános IP-címhez kötődik. Host fejlécek nincsenek érvényesítve.

Áthidaló megoldásként használja a Host Filtering Middleware parancsot. A Host Filtering Middleware-t a Microsoft.AspNetCore.HostFiltering csomag biztosítja, amely implicit módon ASP.NET Core-alkalmazásokhoz érhető el. A köztes szoftvert a CreateDefaultBuilderadja hozzá, amely meghívja a AddHostFiltering-et.

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

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

A host filtering Middleware alapértelmezés szerint le van tiltva. A köztes szoftver engedélyezéséhez definiáljon egy AllowedHosts kulcsot appsettings.json/appsettings.{Environment}.json. Az érték a portszám nélküli gazdagépnevek pontosvesszővel tagolt listája:

appsettings.json:

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

Jegyzet

Továbbított fejlécek Köztes szoftver is rendelkezik AllowedHosts lehetőséggel. A továbbított fejlécek köztes szoftver és a gazdagépszűrési köztes szoftver hasonló funkcióval rendelkeznek a különböző forgatókönyvekhez. A AllowedHosts Továbbításos fejlécek köztes szoftverrel való beállítása akkor megfelelő, ha a Host fejléc nem marad meg, miközben a kéréseket fordított proxykiszolgálóval vagy terheléselosztóval továbbítja. A AllowedHosts gazdagépszűrési köztes szoftverrel való beállítása akkor megfelelő, ha Kestrel nyilvános elérésű peremhálózati kiszolgálóként használják, vagy ha a Host fejlécet közvetlenül továbbítják.

További információért a Továbbított Fejlécek Middleware-ről lásd Az ASP.NET Core konfigurálása proxykiszolgálókkal és terheléselosztókkal.

Libuv átviteli konfiguráció

Libuv (UseLibuv) használatát igénylő projektek esetén:

  • Adjon hozzá függőséget a Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv csomaghoz az alkalmazás projektfájljában:

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

  • Hívás UseLibuv a 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>();
            });
}

HTTP/1.1 kérelem ürítése

A HTTP-kapcsolatok megnyitása időigényes. HTTPS esetén erőforrás-igényes is. Ezért Kestrel a HTTP/1.1 protokoll alapján próbálja újra felhasználni a kapcsolatokat. A kérési törzset teljes mértékben fel kell használni a kapcsolat újrahasználatához. Az alkalmazás nem mindig használja fel a kérelem törzsét, például POST kéréseket, ahol a kiszolgáló átirányítást vagy 404-választ ad vissza. Az POST-redirect esetben:

  • Lehetséges, hogy az ügyfél már elküldte a POST adatok egy részét.
  • A kiszolgáló írja a 301-választ.
  • A kapcsolat csak akkor használható új kéréshez, ha az előző kérelemtörzsből származó POST adatok teljes olvasása megtörtént.
  • Kestrel megpróbálja kiüríteni a kérés törzsét. A kérelem törzsének kiürítése azt jelenti, hogy az adatokat feldolgozás nélkül elolvassuk, majd elvetjük.

A leeresztési folyamat kompromisszumot köt a kapcsolat újbóli felhasználásának engedélyezése és a fennmaradó adatok ürítéséhez szükséges idő között:

  • A ürítés öt másodperces időtúllépéssel rendelkezik, ami nem konfigurálható.
  • Ha a Content-Length vagy Transfer-Encoding fejléc által megadott összes adat nem lett beolvasva az időtúllépés előtt, a kapcsolat lezárul.

Előfordulhat, hogy a válasz megírása előtt vagy után azonnal meg szeretné szüntetni a kérést. Előfordulhat például, hogy az ügyfelek korlátozó adatkorlátokkal rendelkeznek, ezért a feltöltött adatok korlátozása prioritás lehet. Ilyen esetekben a kérés leállításához hívja meg HttpContext.Abort vezérlőből, Razor oldalról vagy köztes szoftverből.

A Abortmeghívására vannak korlátozások:

  • Az új kapcsolatok létrehozása lassú és költséges lehet.
  • Nincs garancia arra, hogy az ügyfél elolvasta a választ, mielőtt a kapcsolat bezárul.
  • A Abort hívásának ritkának kell lennie, és csak súlyos hibák esetén legyen fenntartva, nem gyakori hibák esetén.
    • Csak akkor hívja Abort, ha egy adott problémát meg kell oldani. Hívja például Abort, ha rosszindulatú felhasználók próbálnak POST adatokat megszerezni, vagy ha az ügyfélkódban olyan hiba van, amely nagy számú vagy számos kérést okoz.
    • Ne hívjon olyan gyakori hibahelyzetekhez Abort-t, mint a HTTP 404 (Nem található).

A HttpResponse.CompleteAsync hívása a Abort hívása előtt biztosítja, hogy a kiszolgáló befejezte a válasz írását. Az ügyfél viselkedése azonban nem kiszámítható, és előfordulhat, hogy a kapcsolat megszakadása előtt nem olvassa fel a választ.

Ez a folyamat a HTTP/2 esetében eltérő, mivel a protokoll támogatja az egyes kérésfolyamok megszakítását a kapcsolat bezárása nélkül. Az öt másodperces ürítési időtúllépés nem érvényes. Ha a válasz befejezése után olvasatlan kérés törzsadatai vannak, a kiszolgáló HTTP/2 RST-keretet küld. A rendszer figyelmen kívül hagyja a további kérelemtörzs-adatkereteket.

Ha lehetséges, jobb, ha az ügyfelek használják a Várható: 100-continue kérés fejlécet, és várjanak, amíg a kiszolgáló válaszol, mielőtt elkezdenék elküldeni a kérelem törzsét. Ez lehetővé teszi az ügyfél számára, hogy megvizsgálja a választ, és megszakítsa a szükségtelen adatok elküldése előtt.

További erőforrások