Delen via

Kestrel webserver in ASP.NET Core

  • Artikel

Notitie

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

Door Tom Dykstra, Chris Rossen Stephen Halter

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is de aanbevolen server voor ASP.NET Core en deze is standaard geconfigureerd in ASP.NET Core-projectsjablonen.

de functies van Kestrelzijn:

  • platformoverschrijdend:Kestrel is een platformoverschrijdende webserver die wordt uitgevoerd in Windows, Linux en macOS.
  • Hoge prestaties:Kestrel is geoptimaliseerd voor het efficiënt verwerken van een groot aantal gelijktijdige verbindingen.
  • Lichtgewicht: geoptimaliseerd voor uitvoering in omgevingen met beperkte resources, zoals containers en edge-apparaten.
  • Verhoogde beveiliging:Kestrel ondersteunt HTTPS en is beveiligd tegen beveiligingsproblemen van webservers.
  • Wide-protocolondersteuning:Kestrel ondersteunt algemene webprotocollen, waaronder:
  • Integratie met ASP.NET Core: naadloze integratie met andere ASP.NET Core-onderdelen, zoals de middleware-pijplijn, afhankelijkheidsinjectie en configuratiesysteem.
  • Flexibele workloads: Kestrel ondersteunt verschillende workloads
    • ASP.NET app-frameworks zoals Minimale API's, MVC, Razor pagina's, SignalR, Blazoren gRPC.
    • Een omgekeerde proxy bouwen met YARP-.
  • uitbreidbaarheid:Kestrel aanpassen via configuratie, middleware en aangepaste transporten.
  • Prestatiediagnose:Kestrel biedt ingebouwde functies voor prestatiediagnose, zoals logboekregistratie en metrische gegevens.

Aan de slag gaan

ASP.NET Core-projectsjablonen gebruiken standaard Kestrel wanneer deze niet worden gehost met IIS. In de volgende door de sjabloon gegenereerde Program.csroept de WebApplication.CreateBuilder methode intern UseKestrel aan:

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

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

app.Run();

Voor meer informatie over het configureren van WebApplication en WebApplicationBuilder, zie de Minimale API's snelle referentie.

Optionele clientcertificaten

Zie Optionele clientcertificatenvoor informatie over apps die een subset van de app met een certificaat moeten beveiligen.

Gedrag waarbij foutopsporingsprogramma is gekoppeld

De volgende time-outs en frequentielimieten worden niet afgedwongen wanneer een foutopsporingsprogramma is gekoppeld aan een Kestrel proces:

Aanvullende informatiebronnen

Notitie

Vanaf ASP.NET Core 5.0 is Kestrellibuv transport verouderd. Het libuv-transport ontvangt geen updates voor de ondersteuning van nieuwe besturingssysteemplatforms, zoals Windows ARM64, en wordt verwijderd in een toekomstige release. Verwijder alle aanroepen naar de verouderde methode UseLibuv en gebruik in plaats daarvan het standaard Socket-transport van Kestrel.

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is de webserver die standaard is opgenomen en ingeschakeld in ASP.NET Core-projectsjablonen.

Kestrel ondersteunt de volgende scenario's:

  • HTTPS
  • HTTP/2 (met uitzondering van macOS†)
  • Onduidelijke upgrade die wordt gebruikt om WebSockets in te schakelen
  • Unix-sockets voor hoge prestaties achter Nginx

†HTTP/2 wordt in een toekomstige release ondersteund in macOS.

Kestrel wordt ondersteund op alle platforms en versies die .NET Core ondersteunt.

Aan de slag

ASP.NET Core-projectsjablonen gebruiken standaard Kestrel wanneer deze niet worden gehost met IIS. In de volgende door de sjabloon gegenereerde Program.csroept de WebApplication.CreateBuilder functie intern UseKestrel aan:

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

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

app.Run();

Voor meer informatie over het configureren van WebApplication en WebApplicationBuilder, zie Minimale API's snelle referentie.

Optionele clientcertificaten

Zie Optionele clientcertificatenvoor informatie over apps die een subset van de app met een certificaat moeten beveiligen.

Gedrag wanneer een foutopsporingsprogramma is gekoppeld

De volgende time-outs en frequentielimieten worden niet afgedwongen wanneer een foutopsporingsprogramma is gekoppeld aan een Kestrel proces:

Aanvullende informatiebronnen

Notitie

Vanaf ASP.NET Core 5.0 is Kestrellibuv transport verouderd. Het libuv-transport ontvangt geen updates voor de ondersteuning van nieuwe besturingssysteemplatforms, zoals Windows ARM64, en wordt verwijderd in een toekomstige release. Verwijder alle aanroepen naar de verouderde methode UseLibuv en gebruik in plaats daarvan het standaard Socket-transport van Kestrel.

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is de webserver die standaard is opgenomen en ingeschakeld in ASP.NET Core-projectsjablonen.

Kestrel ondersteunt de volgende scenario's:

  • HTTPS
  • HTTP/2 (met uitzondering van macOS†)
  • Ondoorzichtige upgrade die wordt gebruikt voor de inschakeling van WebSockets
  • Unix-sockets voor hoge prestaties achter Nginx

†HTTP/2 wordt in een toekomstige release ondersteund in macOS.

Kestrel wordt ondersteund op alle platforms en versies die .NET Core ondersteunt.

Voorbeeldcode bekijken of downloaden (hoe te downloaden)

Aan de slag gaan

ASP.NET Core-projectsjablonen gebruiken standaard Kestrel wanneer deze niet worden gehost met IIS. In Program.csroept de ConfigureWebHostDefaults methode UseKestrelaan:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Raadpleeg de secties Een host instellen en Standaard instellingen voor de bouwer van .NET Generic Host in ASP.NET Corevoor meer informatie over het bouwen van de host.

Optionele clientcertificaten

Zie Optionele clientcertificatenvoor informatie over apps die een subset van de app met een certificaat moeten beveiligen.

Aanvullende informatiebronnen

Notitie

Vanaf ASP.NET Core 5.0 is Kestrellibuv transport verouderd. Het libuv-transport ontvangt geen updates voor de ondersteuning van nieuwe besturingssysteemplatforms, zoals Windows ARM64, en wordt verwijderd in een toekomstige release. Verwijder alle aanroepen naar de verouderde methode UseLibuv en gebruik in plaats daarvan het standaard Socket-transport van Kestrel.

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is de webserver die standaard is opgenomen in ASP.NET Core-projectsjablonen.

Kestrel ondersteunt de volgende scenario's:

  • HTTPS
  • Ondoorzichtige upgrade die wordt gebruikt om WebSockets in te schakelen
  • Unix-sockets voor hoge prestaties achter Nginx
  • HTTP/2 (met uitzondering van macOS†)

†HTTP/2 wordt in een toekomstige release ondersteund in macOS.

Kestrel wordt ondersteund op alle platforms en versies die .NET Core ondersteunt.

Voorbeeldcode weergeven of downloaden (hoe te downloaden)

HTTP/2-ondersteuning

HTTP/2- is beschikbaar voor ASP.NET Core-apps als aan de volgende basisvereisten wordt voldaan:

  • Besturingssysteem†
    • Windows Server 2016/Windows 10 of hoger‡
    • Linux met OpenSSL 1.0.2 of hoger (bijvoorbeeld Ubuntu 16.04 of hoger)
  • Doelframework: .NET Core 2.2 of hoger
  • Application-Layer ALPN--verbinding (Protocol Negotiation)
  • TLS 1.2- of hogerverbinding

†HTTP/2 wordt in een toekomstige release ondersteund in macOS. ‡Kestrel heeft beperkte ondersteuning voor HTTP/2 op Windows Server 2012 R2 en Windows 8.1. Ondersteuning is beperkt omdat de lijst met ondersteunde TLS-coderingssuites die beschikbaar zijn op deze besturingssystemen, beperkt is. Een certificaat dat wordt gegenereerd met behulp van een Elliptic Curve Digital Signature Algorithm (ECDSA) is mogelijk vereist om TLS-verbindingen te beveiligen.

Als er een HTTP/2-verbinding tot stand is gebracht, rapporteert HttpRequest.ProtocolHTTP/2.

Vanaf .NET Core 3.0 is HTTP/2 standaard ingeschakeld. Zie de secties Kestrel opties en ListenOptions.Protocols voor meer informatie over configuratie.

Wanneer gebruikt u Kestrel met een omgekeerde proxy

Kestrel kan op zichzelf of met een omgekeerde proxyserver worden gebruikt. Een omgekeerde proxyserver ontvangt HTTP-aanvragen van het netwerk en stuurt deze door naar Kestrel. Voorbeelden van een omgekeerde proxyserver zijn:

Kestrel gebruikt als een edge-webserver (internetgerichte):

Kestrel rechtstreeks met internet communiceert zonder een omgekeerde proxyserver

Kestrel gebruikt in een omgekeerde proxyconfiguratie:

Kestrel indirect communiceert met internet via een omgekeerde proxyserver, zoals IIS, Nginx of Apache

Configuratie, met of zonder een omgekeerde proxyserver, is een ondersteunde hostingconfiguratie.

Kestrel gebruikt als een edge-server zonder een omgekeerde proxyserver biedt geen ondersteuning voor het delen van hetzelfde IP-adres en dezelfde poort tussen meerdere processen. Wanneer Kestrel is geconfigureerd om op een poort te luisteren, verwerkt Kestrel al het verkeer voor die poort, ongeacht de Host headers van aanvragen. Een omgekeerde proxy die poorten kan delen, heeft de mogelijkheid om aanvragen door te sturen naar Kestrel op een uniek IP-adres en een unieke poort.

Zelfs als een omgekeerde proxyserver niet vereist is, kan het gebruik van een omgekeerde proxyserver een goede keuze zijn.

Een omgekeerde proxy:

  • Kan het blootgestelde openbare oppervlak van de apps die door de app worden gehost, beperken.
  • Een extra laag van configuratie en diepgaande cyberbeveiliging bieden.
  • Kan beter worden geïntegreerd met bestaande infrastructuur.
  • Vereenvoudig de configuratie van taakverdeling en beveiligde communicatie (HTTPS). Alleen de omgekeerde proxyserver vereist een X.509-certificaat en die server kan communiceren met de servers van de app op het interne netwerk met behulp van gewone HTTP.

Waarschuwing

Hosten in een reverse proxy-configuratie vereist Configuratie van doorgeschakelde headers middleware.

Kestrel in ASP.NET Core-apps

ASP.NET Core-projectsjablonen gebruiken standaard Kestrel. In Program.csroept de ConfigureWebHostDefaults methode UseKestrelaan:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Voor meer informatie over het bouwen van de host, zie de secties Een host instellen en Standaard bouwerinstellingen van .NET Generic Host in ASP.NET Core.

Als u na het aanroepen van ConfigureWebHostDefaultsextra configuratie wilt opgeven, gebruikt u 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 opties

De Kestrel webserver heeft beperkte configuratieopties die met name handig zijn in internetgerichte implementaties.

Stel beperkingen in voor de eigenschap Limits van de klasse KestrelServerOptions. De eigenschap Limits bevat een exemplaar van de klasse KestrelServerLimits.

In de volgende voorbeelden wordt de Microsoft.AspNetCore.Server.Kestrel.Core-naamruimte gebruikt:

using Microsoft.AspNetCore.Server.Kestrel.Core;

In voorbeelden die verderop in dit artikel worden weergegeven, worden Kestrel opties geconfigureerd in C#-code. Kestrel opties kunnen ook worden ingesteld met behulp van een configuratieprovider. De bestandsconfiguratieprovider kan bijvoorbeeld Kestrel configuratie laden vanuit een appsettings.json- of appsettings.{Environment}.json-bestand:

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

Notitie

KestrelServerOptions en eindpuntconfiguratie kunnen worden geconfigureerd bij configuratieproviders. De resterende Kestrel configuratie moet worden geconfigureerd in C#-code.

Gebruik één uit de volgende methoden:

  • Configureer Kestrel in Startup.ConfigureServices:

    1. Injecteer een exemplaar van IConfiguration in de klasse Startup. In het volgende voorbeeld wordt ervan uitgegaan dat de geïnjecteerde configuratie is toegewezen aan de eigenschap Configuration.

    2. Laad de sectie Kestrel van de configuratie in Startup.ConfigureServicesin de configuratie van Kestrel.

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

  • Configureer Kestrel bij het bouwen van de host:

    Laad in Program.csde Kestrel sectie van de configuratie in Kestrelconfiguratie:

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

Beide methoden werken met elke configuratieprovider.

Keep-alive time-out

KeepAliveTimeout

Hiermee stelt u de time-out voor keep-alive in of haalt u deze op. Standaard ingesteld op 2 minuten.

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

Maximum aantal clientverbindingen

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Het maximum aantal gelijktijdige open TCP-verbindingen kan worden ingesteld voor de hele app met de volgende code:

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

Er is een afzonderlijke limiet voor verbindingen die zijn bijgewerkt van HTTP of HTTPS naar een ander protocol (bijvoorbeeld op een WebSockets-aanvraag). Nadat een verbinding is bijgewerkt, wordt deze niet meegeteld voor de MaxConcurrentConnections limiet.

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

Het maximum aantal verbindingen is standaard onbeperkt (null).

Maximale grootte van verzoeklichaam

MaxRequestBodySize

De standaard maximale grootte van de aanvraagbody is 30.000.000 bytes, wat ongeveer 28,6 MB is.

De aanbevolen methode voor het overschrijven van de limiet in een ASP.NET Core MVC-app is het gebruik van het kenmerk RequestSizeLimitAttribute voor een actiemethode:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Hier volgt een voorbeeld van het configureren van de beperking voor de app voor elke aanvraag:

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

Overschrijf de instelling voor een specifiek verzoek in 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));
    }

Er wordt een uitzondering gegenereerd als de app de limiet voor een aanvraag configureert nadat de app de aanvraag heeft gelezen. Er is een IsReadOnly eigenschap die aangeeft of de eigenschap MaxRequestBodySize de status Alleen-lezen heeft, wat betekent dat het te laat is om de limiet te configureren.

Wanneer een app wordt uitgevoerd out-of-process achter de ASP.NET Core Module, wordt de limiet voor de aanvraagbodygrootte van Kestreluitgeschakeld omdat IIS de limiet al instelt.

Minimale snelheid van hoofdtekst van aanvraag

MinRequestBodyDataRate MinResponseDataRate

Kestrel controleert elke seconde of er gegevens binnenkomen met de opgegeven snelheid in bytes/seconde. Als de snelheid lager is dan het minimum, treedt er een time-out op voor de verbinding. De respijtperiode is de hoeveelheid tijd die Kestrel de client geeft om de verzendsnelheid tot het minimum te verhogen; de snelheid wordt gedurende die tijd niet gecontroleerd. De respijtperiode helpt voorkomen dat verbindingen die in eerste instantie gegevens met een trage snelheid verzenden, worden weggestuurd vanwege een trage TCP-start.

De standaard minimumfrequentie is 240 bytes/seconde met een respijtperiode van 5 seconden.

Een minimumtarief is ook van toepassing op het antwoord. De code voor het instellen van de aanvraaglimiet en de antwoordlimiet is hetzelfde, met uitzondering van het hebben van RequestBody of Response in de eigenschaps- en interfacenamen.

Hier volgt een voorbeeld van het configureren van de minimale gegevenssnelheden in 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);
})

Overschrijf de minimale snelheidslimieten per aanvraag in de 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));
    }

De IHttpMinResponseDataRateFeature waarnaar in het vorige voorbeeld wordt verwezen, is niet aanwezig in HttpContext.Features voor HTTP/2-aanvragen, omdat het wijzigen van frequentielimieten per aanvraag over het algemeen niet wordt ondersteund voor HTTP/2 vanwege de ondersteuning van het protocol voor het aanvragen van multiplexing. De IHttpMinRequestBodyDataRateFeature is echter nog steeds aanwezig HttpContext.Features voor HTTP/2-aanvragen, omdat de leessnelheidslimiet nog steeds volledig kan worden uitgeschakeld per aanvraag door IHttpMinRequestBodyDataRateFeature.MinDataRate in te stellen op null, zelfs voor een HTTP/2-aanvraag. Als u IHttpMinRequestBodyDataRateFeature.MinDataRate probeert te lezen of deze probeert in te stellen op een andere waarde dan null, wordt er een NotSupportedException gegenereerd op basis van een HTTP/2-aanvraag.

Frequentielimieten voor de hele server die via KestrelServerOptions.Limits zijn geconfigureerd, zijn nog steeds van toepassing op zowel HTTP/1.x- als HTTP/2-verbindingen.

Time-out voor aanvraagheaders

RequestHeadersTimeout

Hiermee haalt of stelt u de maximale tijd in die de server besteedt aan het ontvangen van aanvraagheaders. De standaardwaarde is 30 seconden.

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

Maximum aantal streams per verbinding

Http2.MaxStreamsPerConnection beperkt het aantal gelijktijdige aanvraagstromen per HTTP/2-verbinding. Overtollige streams worden geweigerd.

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

De standaardwaarde is 100.

Grootte van kopteksttabel

De HPACK-decoder ontcomprimeert HTTP-headers voor HTTP/2-verbindingen. Http2.HeaderTableSize beperkt de grootte van de headercompressietabel die de HPACK-decoder gebruikt. De waarde wordt opgegeven in octetten en moet groter zijn dan nul (0).

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

De standaardwaarde is 4096.

Maximale framegrootte

Http2.MaxFrameSize geeft de maximale toegestane grootte aan van een nettolading van het HTTP/2-verbindingsframe die is ontvangen of verzonden door de server. De waarde is opgegeven in octetten en moet tussen 2^14 (16.384) en 2^24-1 (16.777.215) zijn.

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

De standaardwaarde is 2^14 (16.384).

Maximale aanvraagheadergrootte

Http2.MaxRequestHeaderFieldSize geeft de maximaal toegestane grootte in octetten van aanvraagheaderwaarden aan. Deze limiet geldt voor zowel de naam als de waarde in de gecomprimeerde en niet-gecomprimeerde weergaven. De waarde moet groter zijn dan nul (0).

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

De standaardwaarde is 8.192.

Oorspronkelijke verbindingsvenstergrootte

Http2.InitialConnectionWindowSize geeft de maximale hoeveelheid gegevens van de aanvraagbody in bytes aan die de server-buffers op hetzelfde moment aggregeren voor alle aanvragen (streams) per verbinding. Aanvragen worden ook beperkt door Http2.InitialStreamWindowSize. De waarde moet groter dan of gelijk zijn aan 65.535 en kleiner dan 2^31 (2.147.483.648).

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

De standaardwaarde is 128 KB (131.072).

Begingrootte van streamvenster

Http2.InitialStreamWindowSize geeft de maximale aanvraaglichaamsgegevens in bytes aan die de server op één moment per aanvraag (stream) buffert. Aanvragen worden ook beperkt door Http2.InitialConnectionWindowSize. De waarde moet groter dan of gelijk zijn aan 65.535 en kleiner dan 2^31 (2.147.483.648).

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

De standaardwaarde is 96 KB (98.304).

Trailers

HTTP-trailers zijn vergelijkbaar met HTTP-headers, behalve dat ze worden verzonden nadat de hoofdtekst van het antwoord is verzonden. Voor IIS en HTTP.sysworden alleen HTTP/2-antwoordtrailers ondersteund.

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

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

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

In de voorgaande voorbeeldcode:

  • SupportsTrailers zorgt ervoor dat voor het antwoord trailers worden ondersteund.
  • DeclareTrailer voegt de opgegeven trailernaam toe aan de Trailer antwoordheader. Het aangeven van de trailers van een reactie is optioneel, maar wordt aanbevolen. Als DeclareTrailer wordt aangeroepen, moet dit zijn voordat de antwoordheaders worden verzonden.
  • AppendTrailer voegt de trailer toe.

Resetten

Met opnieuw instellen kan de server een HTTP/2-aanvraag opnieuw instellen met een opgegeven foutcode. Een resetverzoek wordt beschouwd als afgebroken.

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

Reset in het voorgaande codevoorbeeld geeft de INTERNAL_ERROR foutcode op. Ga voor meer informatie over HTTP/2-foutcodes naar de sectie met foutcodes van de HTTP/2-specificatie.

Synchrone I/O

AllowSynchronousIO bepaalt of synchrone I/O is toegestaan voor de aanvraag en het antwoord. De standaardwaarde is false.

Waarschuwing

Een groot aantal blokkerende synchrone I/O-bewerkingen kan leiden tot starvatie van threadpools, waardoor de app niet meer reageert. Schakel AllowSynchronousIO alleen in wanneer u een bibliotheek gebruikt die geen asynchrone I/O ondersteunt.

In het volgende voorbeeld wordt synchrone I/O ingeschakeld:

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

Zie voor meer informatie over andere Kestrel opties en limieten:

Eindpuntconfiguratie

Standaard wordt ASP.NET Core gebonden aan:

  • http://localhost:5000
  • https://localhost:5001 (wanneer er een lokaal ontwikkelingscertificaat aanwezig is)

Geef URL's op met behulp van:

  • ASPNETCORE_URLS omgevingsvariabele.
  • --urls opdrachtregelargument.
  • urls hostconfiguratiesleutel.
  • UseUrls extensiemethode.

De opgegeven waarde met deze methoden kan een of meer HTTP- en HTTPS-eindpunten zijn (HTTPS als er een standaardcertificaat beschikbaar is). Configureer de waarde als een door puntkomma's gescheiden lijst (bijvoorbeeld "Urls": "http://localhost:8000;http://localhost:8001").

Voor meer informatie over deze benaderingen, zie Server-URLs en configuratie-overschrijving.

Er wordt een ontwikkelingscertificaat gemaakt:

  • Wanneer de .NET Core SDK is geïnstalleerd.
  • Het hulpprogramma dev-certs wordt gebruikt om een certificaat te maken.

Voor sommige browsers is expliciete toestemming vereist om het lokale ontwikkelingscertificaat te vertrouwen.

Projectsjablonen configureren apps die standaard worden uitgevoerd op HTTPS en bevatten HTTPS-omleiding en HSTS-ondersteuning.

Roep Listen of ListenUnixSocket methoden op KestrelServerOptions aan om URL-voorvoegsels en poorten voor Kestrelte configureren.

UseUrlswerken het --urls opdrachtregelargument, urls hostconfiguratiesleutel en de ASPNETCORE_URLS omgevingsvariabele ook, maar hebben de beperkingen die verderop in deze sectie zijn vermeld (er moet een standaardcertificaat beschikbaar zijn voor configuratie van HTTPS-eindpunten).

KestrelServerOptions configuratie:

ConfigureEndpointDefaults(Action<ListenOptions>)

Specificeert een configuratie Action die voor elk opgegeven eindpunt moet worden uitgevoerd. Als ConfigureEndpointDefaults meerdere keren wordt aangeroepen, zullen de eerdere Action's vervangen worden door de laatste gespecificeerde Action.

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

Notitie

Eindpunten die zijn gemaakt door Listenaan te roepen voordatConfigureEndpointDefaults worden aangeroepen, worden de standaardwaarden niet toegepast.

ConfigureerHttpsStandaarden(Action<HttpsConnectionAdapterOpties>)

Specificeert een configuratie Action die voor elk HTTPS-eindpunt moet worden uitgevoerd. Door ConfigureHttpsDefaults meerdere keren aan te roepen, worden eerder opgegeven Action's vervangen door de laatst gespecificeerde Action.

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

Notitie

Eindpunten die zijn gemaakt door Listenaan te roepen voordatConfigureHttpsDefaults worden aangeroepen, worden de standaardwaarden niet toegepast.

Configureren (IConfiguration)

Hiermee maakt u een configuratielaadprogramma voor het instellen van Kestrel waarbij een IConfiguration als invoer wordt gebruikt. De configuratie moet gespecificeerd worden in de configuratiesectie voor Kestrel.

ListenOptions.UseHttps

Configureer Kestrel voor het gebruik van HTTPS.

ListenOptions.UseHttps extensies:

  • UseHttps: configureer Kestrel voor het gebruik van HTTPS met het standaardcertificaat. Genereert een uitzondering als er geen standaardcertificaat is geconfigureerd.
  • 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 parameters:

  • filename is het pad en de bestandsnaam van een certificaatbestand, ten opzichte van de map die de inhoudsbestanden van de app bevat.
  • password is het wachtwoord dat is vereist voor toegang tot de X.509-certificaatgegevens.
  • configureOptions is een Action om de HttpsConnectionAdapterOptionste configureren. Retourneert de ListenOptions.
  • storeName is het certificaatarchief waaruit het certificaat moet worden geladen.
  • subject is de onderwerpnaam voor het certificaat.
  • allowInvalid geeft aan of er ongeldige certificaten moeten worden overwogen, zoals zelfondertekende certificaten.
  • location is de opslaglocatie waaruit het certificaat moet worden geladen.
  • serverCertificate is het X.509-certificaat.

In productie moet HTTPS expliciet worden geconfigureerd. Er moet minimaal een standaardcertificaat worden opgegeven.

Ondersteunde configuraties die hierna worden beschreven:

  • Geen configuratie
  • Het standaardcertificaat vervangen via de configuratie
  • De standaardwaarden in code wijzigen

Geen configuratie

Kestrel luistert op http://localhost:5000 en https://localhost:5001 (als er een standaardcertificaat beschikbaar is).

Het standaardcertificaat uit de configuratie vervangen

CreateDefaultBuilder roept Configure(context.Configuration.GetSection("Kestrel")) standaard aan om Kestrel configuratie te laden. Er is een standaardconfiguratieschema voor HTTPS-app-instellingen beschikbaar voor Kestrel. Configureer meerdere eindpunten, inclusief de URL's en de certificaten die moeten worden gebruikt, vanuit een bestand op schijf of vanuit een certificaatarchief.

In het volgende appsettings.json voorbeeld:

  • Stel AllowInvalid- in op true om het gebruik van ongeldige certificaten toe te staan (bijvoorbeeld zelfondertekende certificaten).
  • Elk HTTPS-eindpunt dat geen certificaat opgeeft (HttpsDefaultCert in het volgende voorbeeld) valt terug op het certificaat dat is gedefinieerd onder Certificaten>Standaard- of het ontwikkelingscertificaat.
{
  "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>"
      }
    }
  }
}

Een alternatief voor het gebruik van Pad en Wachtwoord voor een certificaatknooppunt is het opgeven van het certificaat met behulp van certificaatarchiefvelden. Het Certificaten>Standaardcertificaat kan bijvoorbeeld als volgt worden gespecificeerd:

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

Schemanotities:

  • Namen van eindpunten zijn niet hoofdlettergevoelig. HTTPS en Https zijn bijvoorbeeld geldig.
  • De parameter Url is vereist voor elk eindpunt. De indeling voor deze parameter is hetzelfde als de configuratieparameter op het hoogste niveau Urls, behalve dat deze is beperkt tot één waarde.
  • Deze eindpunten vervangen de eindpunten die zijn gedefinieerd in de configuratie op het hoogste niveau Urls in plaats van ze toe te voegen. Eindpunten die zijn gedefinieerd in code via Listen zijn cumulatief met de eindpunten die zijn gedefinieerd in de configuratiesectie.
  • De sectie Certificate is optioneel. Als de Certificate sectie niet is opgegeven, worden de standaardwaarden gebruikt die zijn gedefinieerd in eerdere scenario's. Als er geen standaardinstellingen beschikbaar zijn, genereert de server een uitzondering en kan deze niet worden gestart.
  • De sectie Certificate ondersteunt zowel Pad-wachtwoord als Onderwerp-opslaan-certificaten.
  • Een willekeurig aantal eindpunten kan op deze manier worden gedefinieerd zolang ze geen poortconflicten veroorzaken.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) retourneert een KestrelConfigurationLoader met een .Endpoint(string name, listenOptions => { }) methode die kan worden gebruikt om de instellingen van een geconfigureerd eindpunt aan te vullen:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader kan direct worden benaderd om door te blijven itereren op de bestaande loader, zoals de loader die door CreateDefaultBuilderwordt geleverd.

  • De configuratiesectie voor elk eindpunt is beschikbaar op de opties in de methode Endpoint, zodat aangepaste instellingen kunnen worden gelezen.
  • Er kunnen meerdere configuraties worden geladen door options.Configure(context.Configuration.GetSection("{SECTION}")) opnieuw aan te roepen met een andere sectie. Alleen de laatste configuratie wordt gebruikt, tenzij Load expliciet wordt aangeroepen op eerdere exemplaren. De metapackage roept geen Load aan, zodat de standaardconfiguratiesectie kan worden vervangen.
  • KestrelConfigurationLoader spiegelt de Listen-familie van API's van KestrelServerOptions als Endpoint-methodenoverloads, zodat code- en configuratie-eindpunten op dezelfde locatie kunnen worden geconfigureerd. Deze overbelastingen gebruiken geen namen en verbruiken alleen standaardinstellingen uit de configuratie.

de standaardinstellingen in code wijzigen

ConfigureEndpointDefaults en ConfigureHttpsDefaults kunnen worden gebruikt om de standaardinstellingen voor ListenOptions en HttpsConnectionAdapterOptionste wijzigen, inclusief het overschrijven van het standaardcertificaat dat in het vorige scenario is opgegeven. ConfigureEndpointDefaults en ConfigureHttpsDefaults moeten worden aangeroepen voordat eindpunten worden geconfigureerd.

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

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

Kestrel ondersteuning voor SNI

SNI- (Server Name Indication) kan worden gebruikt om meerdere domeinen op hetzelfde IP-adres en dezelfde poort te hosten. Om SNI te laten functioneren, verzendt de client de hostnaam voor de beveiligde sessie naar de server tijdens de TLS-handshake, zodat de server het juiste certificaat kan opgeven. De client gebruikt het ingerichte certificaat voor versleutelde communicatie met de server tijdens de beveiligde sessie die de TLS-handshake volgt.

Kestrel ondersteunt SNI via de ServerCertificateSelector callback. De callback wordt eenmaal per verbinding aangeroepen, zodat de app de hostnaam kan inspecteren en het juiste certificaat kan selecteren.

Voor SNI-ondersteuning is het volgende vereist:

  • Wordt uitgevoerd op het doelframework netcoreapp2.1 of hoger. Op net461 of hoger wordt de callback aangeroepen, maar de name is altijd null. De name wordt ook null als de client de hostnaamparameter niet opgeeft in de TLS-handshake.
  • Alle websites worden uitgevoerd op hetzelfde Kestrel exemplaar. Kestrel biedt geen ondersteuning voor het delen van een IP-adres en poort tussen meerdere exemplaren zonder omgekeerde proxy.
webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase);
            certs["localhost"] = localhostCert;
            certs["example.com"] = exampleCert;
            certs["sub.example.com"] = subExampleCert;

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

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

Logboekregistratie van verbindingen

Roep UseConnectionLogging op om Debug-niveau logs te verzenden voor communicatie op byteniveau van een verbinding. Logboekregistratie van verbindingen is handig voor het oplossen van problemen bij communicatie op laag niveau, zoals tijdens TLS-versleuteling en achter proxy's. Als UseConnectionLogging wordt geplaatst voordat UseHttps, wordt versleuteld verkeer geregistreerd. Als UseConnectionLogging na UseHttpswordt geplaatst, wordt ontsleuteld verkeer geregistreerd.

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

Verbinding maken met een TCP-socket

De methode Listen bindt aan een TCP-socket en een opties lambda maakt configuratie van X.509-certificaten mogelijk:

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

In het voorbeeld wordt HTTPS geconfigureerd voor een eindpunt met ListenOptions. Gebruik dezelfde API om andere Kestrel-instellingen voor specifieke eindpunten te configureren.

In Windows kunnen zelfondertekende certificaten worden gemaakt met behulp van de New-SelfSignedCertificate PowerShell-cmdlet. Zie UpdateIISExpressSSLForChrome.ps1voor een niet-ondersteund voorbeeld.

In macOS, Linux en Windows kunnen certificaten worden gemaakt met behulp van OpenSSL-.

Binden aan een Unix-socket

Luister op een Unix-socket met ListenUnixSocket voor verbeterde prestaties met Nginx, zoals wordt weergegeven in dit voorbeeld:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • Stel in het Nginx-configuratiebestand de server>location>proxy_pass vermelding in op http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} is de naam van de socket die is opgegeven voor ListenUnixSocket (bijvoorbeeld kestrel-test.sock in het vorige voorbeeld).
  • Zorg ervoor dat de socket kan worden geschreven door Nginx (bijvoorbeeld chmod go+w /tmp/kestrel-test.sock).

Poort 0

Wanneer het poortnummer 0 is opgegeven, wordt Kestrel dynamisch verbonden met een beschikbare poort. In het volgende voorbeeld ziet u hoe u kunt bepalen welke poort Kestrel tijdens runtime daadwerkelijk is gebonden:

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

Wanneer de app wordt uitgevoerd, geeft de uitvoer van het consolevenster de dynamische poort aan waar de app kan worden bereikt:

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

Beperkingen

Configureer eindpunten met de volgende methoden:

  • UseUrls
  • --urls opdrachtregelargument
  • urls host-configuratiesleutel
  • omgevingsvariabele ASPNETCORE_URLS

Deze methoden zijn handig om code te laten werken met andere servers dan Kestrel. Houd echter rekening met de volgende beperkingen:

  • HTTPS kan niet worden gebruikt met deze benaderingen, tenzij er een standaardcertificaat wordt opgegeven in de configuratie van het HTTPS-eindpunt (bijvoorbeeld met behulp van KestrelServerOptions configuratie of een configuratiebestand, zoals eerder in dit onderwerp wordt weergegeven).
  • Wanneer zowel de Listen als UseUrls benaderingen tegelijkertijd worden gebruikt, overschrijven de Listen eindpunten de UseUrls eindpunten.

Configuratie van IIS-eindpunt

Wanneer u IIS gebruikt, worden de URL-bindingen voor IIS-onderdrukkingsbindingen ingesteld door Listen of UseUrls. Zie het onderwerp ASP.NET Core Module voor meer informatie.

LuisterOpties.Protocols

Met de eigenschap Protocols worden de HTTP-protocollen (HttpProtocols) ingesteld die zijn ingeschakeld op een verbindingseindpunt of voor de server. Wijs een waarde toe aan de eigenschap Protocols uit de HttpProtocols enum.

HttpProtocols opsommingswaarde Verbindingsprotocol toegestaan
Http1 Alleen HTTP/1.1. Kan worden gebruikt met of zonder TLS.
Http2 Alleen HTTP/2. Kan alleen zonder TLS worden gebruikt als de client ondersteuning biedt voor een Prior Knowledge Mode.
Http1AndHttp2 HTTP/1.1 en HTTP/2. HTTP/2 vereist dat de client HTTP/2 selecteert in de TLS Application-Layer Protocol Negotiation (ALPN) handshake; anders wordt de verbinding standaard ingesteld op HTTP/1.1.

De standaardwaarde ListenOptions.Protocols voor elk eindpunt is HttpProtocols.Http1AndHttp2.

TLS-beperkingen voor HTTP/2:

  • TLS-versie 1.2 of hoger
  • Heronderhandeling uitgeschakeld
  • Compressie uitgeschakeld
  • Minimale kortstondige sleuteluitwisselingsgrootten:
    • Elliptische curve Diffie-Hellman (ECDHE) [RFC4492]: minimaal 224 bits
    • Eindig veld Diffie-Hellman (DHE) [TLS12]: minimaal 2048 bits
  • De coderingssuite is niet verboden.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] met de P-256 elliptische curve [FIPS186] wordt standaard ondersteund.

In het volgende voorbeeld worden HTTP/1.1- en HTTP/2-verbindingen op poort 8000 toegestaan. Verbindingen worden beveiligd door TLS met een opgegeven certificaat:

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

Gebruik Verbindings-middleware om TLS-handshakes per verbinding te filteren voor specifieke coderingen, indien nodig.

Het volgende voorbeeld genereert NotSupportedException voor een coderingsalgoritmen die niet door de app worden ondersteund. U kunt ook ITlsHandshakeFeature.CipherAlgorithm definiëren en vergelijken met een lijst met acceptabele coderingssuites.

Er wordt geen versleuteling gebruikt met een CipherAlgorithmType.Null coderingsalgoritme.

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

Verbindingsfilters kunnen ook worden geconfigureerd via een 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();
        });
    });
});

In Linux kan CipherSuitesPolicy worden gebruikt om TLS-handshakes per verbinding te filteren:

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

het protocol instellen vanuit configuratie-

CreateDefaultBuilder roept serverOptions.Configure(context.Configuration.GetSection("Kestrel")) standaard aan om Kestrel configuratie te laden.

In het volgende appsettings.json voorbeeld wordt HTTP/1.1 tot stand gebracht als het standaardverbindingsprotocol voor alle eindpunten:

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

In het volgende appsettings.json voorbeeld wordt het HTTP/1.1-verbindingsprotocol voor een specifiek eindpunt vastgesteld:

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

Protocollen die zijn opgegeven in code overschrijven waarden die zijn ingesteld door de configuratie.

URL-voorvoegsels

Wanneer u UseUrlsgebruikt, --urls opdrachtregelargument, urls hostconfiguratiesleutel of ASPNETCORE_URLS omgevingsvariabele, kunnen de URL-voorvoegsels een van de volgende indelingen hebben.

Alleen HTTP-URL-voorvoegsels zijn geldig. Kestrel biedt geen ondersteuning voor HTTPS bij het configureren van URL-bindingen met behulp van UseUrls.

  • IPv4-adres met poortnummer

    http://65.55.39.10:80/

    0.0.0.0 is een speciaal geval dat is gekoppeld aan alle IPv4-adressen.

  • IPv6-adres met poortnummer

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

    [::] is het IPv6-equivalent van IPv4-0.0.0.0.

  • Hostnaam met poortnummer

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

    Hostnamen, *en +, zijn niets bijzonders. Alles wat niet wordt herkend als een geldig IP-adres of localhost bindt aan alle IPv4- en IPv6-IP-adressen. Als u verschillende hostnamen wilt binden aan verschillende ASP.NET Core-apps op dezelfde poort, gebruikt u HTTP.sys of een omgekeerde proxyserver, zoals IIS, Nginx of Apache.

    Waarschuwing

    Hosten in een reverse proxy-configuratie vereist Middleware configuratie voor doorgestuurde headers.

  • Hostnaam localhost met poortnummer of loopback-IP met poortnummer

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

    Wanneer localhost is opgegeven, probeert Kestrel verbinding te maken met zowel IPv4- als IPv6-loopback-interfaces. Als de aangevraagde poort wordt gebruikt door een andere service in een loopback-interface, kan Kestrel niet worden gestart. Als een loopback-interface om een andere reden niet beschikbaar is (meestal omdat IPv6 niet wordt ondersteund), Kestrel een waarschuwing registreert.

Filtering van hosts

Hoewel Kestrel ondersteuning biedt voor configuratie op basis van voorvoegsels zoals http://example.com:5000, negeert Kestrel de hostnaam grotendeels. Host-localhost is een speciaal geval dat wordt gebruikt voor binding met loopback-adressen. Elke andere host dan een expliciet IP-adres bindt aan alle openbare IP-adressen. Host headers worden niet gevalideerd.

Gebruik Host Filtering Middleware als tijdelijke oplossing. Host filtering Middleware wordt geleverd door het Microsoft.AspNetCore.HostFiltering pakket, dat impliciet wordt geleverd voor ASP.NET Core-apps. De middleware wordt toegevoegd door CreateDefaultBuilder, die AddHostFilteringaanroept:

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

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

Host Filtering Middleware is standaard uitgeschakeld. Als u de middleware wilt inschakelen, definieert u een AllowedHosts-sleutel in appsettings.json/appsettings.{Environment}.json. De waarde is een door puntkomma's gescheiden lijst met hostnamen zonder poortnummers:

appsettings.json:

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

Notitie

Doorgestuurde Headers Middleware- heeft ook een optie AllowedHosts. Middleware voor doorgestuurde headers en Host Filtering Middleware hebben vergelijkbare functionaliteit voor verschillende scenario's. Het instellen van AllowedHosts met Middleware voor doorgeschakelde headers is geschikt wanneer de Host-header niet wordt behouden tijdens het doorsturen van aanvragen met een omgekeerde proxyserver of load balancer. Het instellen van AllowedHosts met Host Filtering Middleware is geschikt wanneer Kestrel wordt gebruikt als een openbare randserver of wanneer de Host header rechtstreeks wordt doorgestuurd.

Voor meer informatie over Middleware voor doorgeschakelde headers, zie Configureer ASP.NET Core voor gebruik met proxyservers en load balancers.

Libuv-transportconfiguratie

Voor projecten waarvoor het gebruik van Libuv (UseLibuv) is vereist:

  • Voeg een afhankelijkheid voor het Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv-pakket toe aan het projectbestand van de app:

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

  • Bel UseLibuv op de 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 aanvraag leegmaken

Het openen van HTTP-verbindingen kost veel tijd. Voor HTTPS is het ook resource-intensief. Daarom probeert Kestrel verbindingen opnieuw te gebruiken volgens het HTTP/1.1-protocol. De inhoud van het verzoek moet volledig worden gebruikt om de verbinding opnieuw te kunnen gebruiken. De app gebruikt niet altijd de aanvraagbody, zoals bij een POST-aanvraag waarbij de server een omleiding of 404-antwoord retourneert. In het POST-redirect-geval:

  • De client heeft mogelijk al een deel van de POST gegevens verzonden.
  • De server schrijft het 301-antwoord.
  • De verbinding kan pas worden gebruikt voor een nieuwe aanvraag als de POST gegevens uit de vorige aanvraagtekst volledig zijn gelezen.
  • Kestrel probeert de aanvraagbody leeg te maken. Het leegmaken van de aanvraagtekst betekent dat de gegevens worden gelezen en verwijderd zonder deze te verwerken.

Het afvoerproces zorgt voor een afweging tussen het opnieuw gebruiken van de verbinding en de tijd die nodig is om resterende gegevens leeg te maken:

  • Leegmaken heeft een time-out van vijf seconden, die niet kan worden geconfigureerd.
  • Als alle gegevens die zijn opgegeven door de Content-Length of Transfer-Encoding header niet zijn gelezen vóór de time-out, wordt de verbinding gesloten.

Soms wilt u de aanvraag onmiddellijk beëindigen, vóór of na het schrijven van het antwoord. Clients kunnen bijvoorbeeld beperkende gegevenslimieten hebben, dus het beperken van geüploade gegevens kan een prioriteit zijn. In dergelijke gevallen om een aanvraag te beëindigen, roept u HttpContext.Abort aan vanuit een controller, Razor Page, of middleware.

Er zijn opmerkingen bij het aanroepen van Abort:

  • Het maken van nieuwe verbindingen kan traag en duur zijn.
  • Er is geen garantie dat de client het antwoord heeft gelezen voordat de verbinding wordt gesloten.
  • Het aanroepen van Abort moet zeldzaam zijn en gereserveerd zijn voor ernstige foutgevallen, geen veelvoorkomende fouten.
    • Roep alleen Abort aan wanneer een specifiek probleem moet worden opgelost. Roep bijvoorbeeld Abort aan als kwaadwillende clients proberen gegevens te POST of wanneer er een fout in clientcode is die grote of talrijke aanvragen veroorzaakt.
    • Roep geen Abort aan voor veelvoorkomende foutsituaties, zoals HTTP 404 (niet gevonden).

Het aanroepen van HttpResponse.CompleteAsync- voordat u Abort aanroept, zorgt ervoor dat de server het schrijven van het antwoord heeft voltooid. Clientgedrag is echter niet voorspelbaar en ze lezen het antwoord mogelijk niet voordat de verbinding wordt afgebroken.

Dit proces verschilt voor HTTP/2 omdat het protocol ondersteuning biedt voor het afboren van afzonderlijke aanvraagstreams zonder de verbinding te sluiten. De time-out van vijf seconden voor afvoer is niet van toepassing. Als er ongelezen aanvraagtekstgegevens zijn na het voltooien van een antwoord, verzendt de server een HTTP/2 RST-frame. Aanvullende gegevensframes van het aanvraaglichaam worden genegeerd.

Indien mogelijk is het beter voor cliënten om de Verwachten: 100-continue verzoekheader te gebruiken en te wachten tot de server reageert voordat de verzoekinhoud wordt verzonden. Dit geeft de client de mogelijkheid om het antwoord te onderzoeken en af te breken voordat overbodige gegevens worden verzonden.

Aanvullende informatiebronnen