Dela via

Kestrel webbserver i ASP.NET Core

  • Artikel

Obs

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av denna artikel.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. Den aktuella versionen finns i den .NET 9-versionen av den här artikeln.

Viktig

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För att se den aktuella versionen, se .NET 9-versionen av den här artikeln .

Av Tom Dykstra, Chris Ross, och Stephen Halter

Kestrel är en plattformsoberoende webbserver för ASP.NET Core. Kestrel är den rekommenderade servern för ASP.NET Core och konfigureras som standard i ASP.NET Core-projektmallar.

Kestrel:s funktioner omfattar följande:

  • plattformsoberoende:Kestrel är en plattformsoberoende webbserver som körs i Windows, Linux och macOS.
  • Höga prestanda:Kestrel är optimerad för att effektivt hantera ett stort antal samtidiga anslutningar.
  • Lättvikt: Optimerad för körning i resursbegränsade miljöer, till exempel containrar och kantenheter.
  • Säkerhet härdad:Kestrel stöder HTTPS och är härdad mot säkerhetsrisker på webbservern.
  • Wide Protocol-stöd:Kestrel stöder vanliga webbprotokoll, inklusive:
  • Integrering med ASP.NET Core: sömlös integrering med andra ASP.NET Core-komponenter, till exempel pipelinen för mellanprogram, beroendeinmatning och konfigurationssystemet.
  • Flexibla arbetsbelastningar: Kestrel stöder många arbetsbelastningar:
    • ASP.NET appramverk som Minimala API:er, MVC, Razor sidor, SignalR, Blazoroch gRPC.
    • Skapa en omvänd proxy med YARP-.
  • Utökningsbarhet: Anpassa Kestrel via konfiguration, mellanprogram och anpassade transporter.
  • Prestandadiagnostik:Kestrel innehåller inbyggda funktioner för prestandadiagnostik, till exempel loggning och mått.

Sätta igång

ASP.NET Core-projektmallar använder Kestrel som standard när de inte finns med IIS. I följande mallgenererade Program.csanropar WebApplication.CreateBuilder-metoden UseKestrel internt.

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

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

app.Run();

Mer information om hur du konfigurerar WebApplication och WebApplicationBuilderfinns i snabbreferensen minimala API:er.

Valfria klientcertifikat

Information om appar som måste skydda en delmängd av appen med ett certifikat finns i Valfria klientcertifikat.

Beteende med felsökningsprogrammet anslutet

Följande tidsgränser och hastighetsgränser tillämpas inte när ett felsökningsprogram är kopplat till en Kestrel process:

Ytterligare resurser

Not

Från och med ASP.NET Core 5.0 är Kestrel's libuv transport föråldrad. Libuv-transporten tar inte emot uppdateringar för att stödja nya OS-plattformar, till exempel Windows ARM64, och tas bort i en framtida version. Ta bort alla anrop till den föråldrade UseLibuv-metoden och använd Kestrelstandard-Socket-transport i stället.

Kestrel är en plattformsoberoende webbserver för ASP.NET Core. Kestrel är webbservern som ingår och aktiveras som standard i ASP.NET Core-projektmallar.

Kestrel stöder följande scenarier:

  • HTTPS
  • HTTP/2 (förutom i macOS†)
  • Ogenomskinlig uppgradering som används för att aktivera WebSockets
  • Unix-socketar för höga prestanda bakom Nginx

†HTTP/2 kommer att stödjas på macOS i en framtida version.

Kestrel stöds på alla plattformar och versioner som .NET Core stöder.

Sätta igång

ASP.NET Core-projektmallar använder Kestrel som standard när de inte är värd med IIS. I följande mallgenererade Program.csanropar WebApplication.CreateBuilder-metoden UseKestrel internt:

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

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

app.Run();

Mer information om hur du konfigurerar WebApplication och WebApplicationBuilderfinns i snabbreferensen minimala API:er.

Valfria klientcertifikat

Information om appar som måste skydda en delmängd av appen med ett certifikat finns i Valfria klientcertifikat.

Beteende med felsökningsprogrammet anslutet

Följande tidsgränser och hastighetsgränser tillämpas inte när ett felsökningsprogram är kopplat till en Kestrel process:

Ytterligare resurser

Anteckning

Från och med ASP.NET Core 5.0 är Kestrel's libuv transport föråldrad. Libuv-transporten tar inte emot uppdateringar för att stödja nya OS-plattformar, till exempel Windows ARM64, och tas bort i en framtida version. Ta bort alla anrop till den föråldrade UseLibuv-metoden och använd Kestrelstandard-Socket-transport i stället.

Kestrel är en plattformsoberoende webbserver för ASP.NET Core. Kestrel är webbservern som ingår och aktiveras som standard i ASP.NET Core-projektmallar.

Kestrel stöder följande scenarier:

  • HTTPS
  • HTTP/2 (förutom i macOS†)
  • Ogenomskinlig uppgradering som används för att aktivera WebSockets
  • Unix-socketar för höga prestanda bakom Nginx

†HTTP/2 kommer att stödjas på macOS i en framtida version.

Kestrel stöds på alla plattformar och versioner som .NET Core stöder.

Visa eller ladda ned exempelkod (hur du laddar ned)

Sätta igång

ASP.NET Core-projektmallar använder Kestrel som standard när de inte körs med IIS. I Program.csanropar metoden ConfigureWebHostDefaultsUseKestrel:

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

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

För mer information om hur du bygger värden, se avsnitten Konfigurera en värd och Standardinställningar för builder i .NET Generic Host i ASP.NET Core.

Valfria klientcertifikat

Information om appar som måste skydda en delmängd av appen med ett certifikat finns i Valfria klientcertifikat.

Ytterligare resurser

Not

Från och med ASP.NET Core 5.0 är Kestrel's libuv transport föråldrad. Libuv-transporten tar inte emot uppdateringar för att stödja nya OS-plattformar, till exempel Windows ARM64, och tas bort i en framtida version. Ta bort alla anrop till den föråldrade UseLibuv-metoden och använd Kestrelstandard-Socket-transport i stället.

Kestrel är en plattformsoberoende webbserver för ASP.NET Core. Kestrel är webbservern som ingår som standard i ASP.NET Core-projektmallar.

Kestrel stöder följande scenarier:

  • HTTPS
  • Ogenomskinlig uppgradering som används för att aktivera WebSockets
  • Unix-socketar för höga prestanda bakom Nginx
  • HTTP/2 (förutom i macOS†)

†HTTP/2 kommer att stödjas på macOS i en framtida version.

Kestrel stöds på alla plattformar och versioner som .NET Core stöder.

Visa eller ladda ned exempelkod (hur du laddar ned)

HTTP/2-stöd

HTTP/2 är tillgängligt för ASP.NET Core-appar om följande grundläggande krav uppfylls:

  • Operativsystem†
    • Windows Server 2016/Windows 10 eller senare‡
    • Linux med OpenSSL 1.0.2 eller senare (till exempel Ubuntu 16.04 eller senare)
  • Målramverk: .NET Core 2.2 eller senare
  • Application-Layer Protocol Negotiation (ALPN) anslutning
  • TLS 1.2 eller senare anslutning

†HTTP/2 kommer att stödjas på macOS i en framtida version. ‡Kestrel har begränsat stöd för HTTP/2 på Windows Server 2012 R2 och Windows 8.1. Stödet är begränsat eftersom listan över TLS-chiffersviter som stöds är begränsad på dessa operativsystem. Ett certifikat som genereras med hjälp av en Elliptic Curve Digital Signature Algorithm (ECDSA) kan krävas för att skydda TLS-anslutningar.

Om en HTTP/2-anslutning upprättas, rapporterar HttpRequest.ProtocolHTTP/2.

Från och med .NET Core 3.0 är HTTP/2 aktiverat som standard. Mer information om konfiguration finns i avsnitten Kestrel alternativ och ListenOptions.Protocols.

När du ska använda Kestrel med en omvänd proxy

Kestrel kan användas av sig själv eller med en omvänd proxyserver. En omvänd proxyserver tar emot HTTP-begäranden från nätverket och vidarebefordrar dem till Kestrel. Exempel på en omvänd proxyserver är:

Kestrel används som en gränswebbserver (Internetuppkopplad):

Kestrel kommunicerar direkt med Internet utan en omvänd proxyserver

Kestrel som används i en omvänd proxykonfiguration:

Kestrel kommunicerar indirekt med Internet via en omvänd proxyserver, till exempel IIS, Nginx eller Apache

Antingen är konfigurationen, med eller utan en omvänd proxyserver, en värdkonfiguration som stöds.

Kestrel som används som en gränsserver utan en omvänd proxyserver stöder inte delning av samma IP-adress och port mellan flera processer. När Kestrel har konfigurerats för att lyssna på en port hanterar Kestrel all trafik för porten oavsett begärandens Host huvuden. En omvänd proxy som kan dela portar har möjlighet att vidarebefordra begäranden till Kestrel på en unik IP-adress och port.

Även om en omvänd proxyserver inte krävs kan det vara ett bra val att använda en omvänd proxyserver.

En omvänd proxy:

  • Kan begränsa den exponerade offentliga ytan för de appar som den är värd för.
  • Tillhandahåll ett ytterligare lager av konfiguration och fördjupad cybersäkerhet.
  • Kan integreras bättre med befintlig infrastruktur.
  • Förenkla belastningsutjämning och konfiguration av säker kommunikation (HTTPS). Endast den omvända proxyservern kräver ett X.509-certifikat och den servern kan kommunicera med appens servrar i det interna nätverket med vanlig HTTP.

Varning

Värdtjänster i en konfiguration av omvänd proxy kräver mellanprogram för vidarebefordrade huvudkonfigurationer.

Kestrel i ASP.NET Core-appar

ASP.NET Core-projektmallar använder Kestrel som standard. I Program.csanropar metoden ConfigureWebHostDefaultsUseKestrel.

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

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

Mer information om hur du bygger värden finns i avsnitten Konfigurera en värd och Standardinställningar för byggare i .NET Generic Host i ASP.NET Core.

Om du vill ange ytterligare konfiguration efter att du har anropat ConfigureWebHostDefaultsanvänder du 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 alternativ

Den Kestrel webbservern har konfigurationsalternativ för begränsningar som är särskilt användbara i Internetuppkopplade distributioner.

Ange begränsningar för egenskapen Limits för klassen KestrelServerOptions. Egenskapen Limits innehåller en instans av klassen KestrelServerLimits.

I följande exempel används namnområdet Microsoft.AspNetCore.Server.Kestrel.Core:

using Microsoft.AspNetCore.Server.Kestrel.Core;

I exempel som visas senare i den här artikeln konfigureras Kestrel alternativ i C#-kod. Kestrel-alternativ kan också konfigureras med hjälp av en konfigurationsleverantör. Till exempel kan filkonfigurationsprovidern läsa in Kestrel konfiguration från en appsettings.json- eller appsettings.{Environment}.json-fil:

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

Notera

KestrelServerOptions och slutpunktskonfiguration kan konfigureras av konfigurationsleverantörer. Återstående Kestrel konfiguration måste konfigureras i C#-kod.

Använd en av följande metoder:

  • Konfigurera Kestrel i Startup.ConfigureServices:

    1. Injicera en instans av IConfiguration i klassen Startup. I följande exempel förutsätts att den inmatade konfigurationen har tilldelats egenskapen Configuration.

    2. I Startup.ConfigureServices, ladda avsnittet Kestrel till Kestrel:s konfiguration.

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

  • Konfigurera Kestrel när du skapar värd:

    I Program.cs, ladda in konfigurationsavsnittet Kestrel i Kestrel:s konfiguration.

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

Båda ovanstående metoder fungerar med alla konfigurationsprovider.

Timeout för keep-alive

KeepAliveTimeout

Hämtar eller ställer in keep-alive-timeout. Standardvärdet är 2 minuter.

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

Maximalt antal klientanslutningar

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Det maximala antalet samtidiga öppna TCP-anslutningar kan anges för hela appen med följande kod:

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

Det finns en separat gräns för anslutningar som har uppgraderats från HTTP eller HTTPS till ett annat protokoll (till exempel på en WebSockets-begäran). När en anslutning har uppgraderats räknas den inte mot gränsen för MaxConcurrentConnections.

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

Det maximala antalet anslutningar är obegränsat (null) som standard.

Maximal storlek på begärandetext

MaxRequestBodySize

Standardstorleken för begärandetexten är 30 000 000 byte, vilket är cirka 28,6 MB.

Den rekommenderade metoden för att åsidosätta gränsen i en ASP.NET Core MVC-app är att använda attributet RequestSizeLimitAttribute för en åtgärdsmetod:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Här är ett exempel som visar hur du konfigurerar villkoret för appen för varje begäran:

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

Åsidosätt inställningen för en specifik begäran i mellanprogram:

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

Ett undantag utlöses om appen konfigurerar gränsen för en begäran när appen har börjat läsa begäran. Det finns en egenskap IsReadOnly som anger om egenskapen MaxRequestBodySize är skrivskyddad, vilket innebär att det är för sent att konfigurera gränsen.

När en app körs out-of-process bakom ASP.NET Core Moduleinaktiveras Kestrelstorleksgräns för begärandetext eftersom IIS redan anger gränsen.

Minsta datafrekvens för begärandetext

MinRequestBodyDataRate MinResponseDataRate

Kestrel kontrollerar varje sekund om data anländer till den angivna hastigheten i byte/sekund. Om hastigheten sjunker under minimivärdet avbryts anslutningen. Respitperioden är den tid som Kestrel ger klienten för att öka sin sändningshastighet upp till minimivärdet; hastigheten kontrolleras inte under den tiden. Respitperioden hjälper till att undvika att släppa anslutningar som ursprungligen skickar data i långsam takt på grund av långsam TCP-start.

Standardvärdet är 240 byte/sekund med en respitperiod på 5 sekunder.

En minimifrekvens gäller även för svaret. Koden för att ange begärandegränsen och svarsgränsen är densamma förutom att ha RequestBody eller Response i egenskaps- och gränssnittsnamnen.

Här är ett exempel som visar hur du konfigurerar de lägsta datafrekvenserna i 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);
})

Åsidosätt de lägsta hastighetsgränserna per begäran i mellanprogram:

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

Den IHttpMinResponseDataRateFeature som refereras i det tidigare exemplet finns inte i HttpContext.Features för HTTP/2-begäranden eftersom ändring av hastighetsbegränsningar per begäran i allmänhet inte stöds för HTTP/2 på grund av protokollets stöd för multiplexering av begäranden. Men IHttpMinRequestBodyDataRateFeature finns fortfarande HttpContext.Features för HTTP/2-begäranden, eftersom läsfrekvensgränsen fortfarande kan inaktiveras helt per begäran genom att ange IHttpMinRequestBodyDataRateFeature.MinDataRate till null även för en HTTP/2-begäran. Försök att läsa IHttpMinRequestBodyDataRateFeature.MinDataRate eller att sätta det till ett annat värde än null kommer att leda till att en NotSupportedException kastas vid en HTTP/2-begäran.

Hastighetsbegränsningar för hela servern som konfigurerats via KestrelServerOptions.Limits gäller fortfarande för både HTTP/1.x- och HTTP/2-anslutningar.

Tidsgräns för begäranhuvuden

RequestHeadersTimeout

Hämtar eller anger den maximala tid som servern ägnar åt att ta emot begärandehuvuden. Standardvärdet är 30 sekunder.

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

Maximalt antal strömmar per anslutning

Http2.MaxStreamsPerConnection begränsar antalet samtidiga begärandeströmmar per HTTP/2-anslutning. Överflödiga strömmar avvisas.

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

Standardvärdet är 100.

Rubriktabellstorlek

HPACK-avkodaren dekomprimerar HTTP-huvuden för HTTP/2-anslutningar. Http2.HeaderTableSize begränsar storleken på den rubrikkomprimeringstabell som HPACK-avkodaren använder. Värdet anges i oktetter och måste vara större än noll (0).

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

Standardvärdet är 4096.

Maximal ramstorlek

Http2.MaxFrameSize anger den maximala tillåtna storleken på en HTTP/2-anslutningsramsnyttolast som tas emot eller skickas av servern. Värdet anges i oktetter och måste vara mellan 2^14 (16 384) och 2^24-1 (16 777 215).

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

Standardvärdet är 2^14 (16 384).

Maximal storlek för begärandehuvud

Http2.MaxRequestHeaderFieldSize anger den maximala tillåtna storleken i oktetter av värden för begärandehuvud. Den här gränsen gäller både namn och värde i deras komprimerade och okomprimerade representationer. Värdet måste vara större än noll (0).

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

Standardvärdet är 8 192.

Ursprunglig storlek på anslutningsfönstret

Http2.InitialConnectionWindowSize anger det maximala antalet brödtextdata för begäranden i byte som servern buffrar samtidigt aggregerade över alla begäranden (strömmar) per anslutning. Begäranden begränsas också av Http2.InitialStreamWindowSize. Värdet måste vara större än eller lika med 65 535 och mindre än 2^31 (2 147 483 648).

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

Standardvärdet är 128 KB (131 072).

Storlek på inledande strömsfönster

Http2.InitialStreamWindowSize anger maximalt antal brödtextdata för begäran i byte som servern buffrar samtidigt per begäran (dataström). Begäranden begränsas också av Http2.InitialConnectionWindowSize. Värdet måste vara större än eller lika med 65 535 och mindre än 2^31 (2 147 483 648).

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

Standardvärdet är 96 KB (98 304).

Släp

HTTP-trailers liknar HTTP-huvuden, förutom att de skickas efter att svarstexten har skickats. För IIS och HTTP.sysstöds endast HTTP/2-svarstrailer.

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

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

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

I föregående exempelkod:

  • SupportsTrailers ser till att släpvagnar stöds för svaret.
  • DeclareTrailer lägger till det angivna trailernamnet i Trailer-svarsrubriken. Att deklarera ett svars släpvagnar är valfritt, men rekommenderas. Om DeclareTrailer anropas måste det vara innan svarsrubrikerna skickas.
  • AppendTrailer lägger till släpet.

Återställ

Med återställning kan servern återställa en HTTP/2-begäran med en angiven felkod. En återställningsbegäran anses avbruten.

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

Reset i föregående kodexempel anger INTERNAL_ERROR felkod. Mer information om HTTP/2-felkoder finns i avsnittet HTTP/2-specifikationsfelkod.

Synkront I/O

AllowSynchronousIO styr om synkron I/O tillåts för begäran och svar. Standardvärdet är false.

Varning

Ett stort antal blockerande synkrona I/O-åtgärder kan leda till utsvulten trådpool, vilket gör att appen inte svarar. Aktivera endast AllowSynchronousIO när du använder ett bibliotek som inte stöder asynkron I/O.

Följande exempel aktiverar synkron I/O:

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

Information om andra Kestrel alternativ och gränser finns i:

Slutpunktskonfiguration

Som standard binder ASP.NET Core till:

  • http://localhost:5000
  • https://localhost:5001 (när ett lokalt utvecklingscertifikat finns)

Ange URL:er med hjälp av:

  • ASPNETCORE_URLS miljövariabel.
  • --urls kommandoradsargument.
  • urls värdkonfigurationsnyckel.
  • UseUrls tilläggsmetod.

Värdet som anges med dessa metoder kan vara en eller flera HTTP- och HTTPS-slutpunkter (HTTPS om ett standardcertifikat är tillgängligt). Konfigurera värdet som en semikolonavgränsad lista (till exempel "Urls": "http://localhost:8000;http://localhost:8001").

Mer information om dessa metoder finns i Server-URL:er och åsidosättningskonfiguration.

Ett utvecklingscertifikat skapas:

Vissa webbläsare kräver att du beviljar explicit behörighet att lita på det lokala utvecklingscertifikatet.

Projektmallar konfigurerar appar att köras på HTTPS som standard och inkluderar HTTPS-omdirigering och HSTS-stöd.

Anropa Listen eller ListenUnixSocket metoder på KestrelServerOptions för att konfigurera URL-prefix och portar för Kestrel.

UseUrlsfungerar också med --urls kommandoradsargument, urls värdkonfigurationsnyckel och ASPNETCORE_URLS miljövariabeln, men har de begränsningar som anges senare i det här avsnittet (ett standardcertifikat måste vara tillgängligt för konfiguration av HTTPS-slutpunkter).

KestrelServerOptions konfiguration:

Konfigurera standardinställningar för slutpunkter (Action<ListenOptions>)

Anger en konfiguration Action som ska köras för varje angiven slutpunkt. Om du anropar ConfigureEndpointDefaults flera gånger ersätts tidigare Actionmed de senaste Action angivna.

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

Anteckning

Slutpunkter som skapas genom att anropa Listeninnan anropar ConfigureEndpointDefaults har inte standardvärdena tillämpade.

KonfigureraHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Anger en konfiguration Action som ska köras för varje HTTPS-slutpunkt. Om du anropar ConfigureHttpsDefaults flera gånger ersätts tidigare Actionmed de senaste Action angivna.

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

Not

Slutpunkter som skapas genom att anropa Listeninnan anropar ConfigureHttpsDefaults har inte standardvärdena tillämpade.

Configure(IConfiguration)

Skapar en konfigurationsinläsare för att konfigurera Kestrel som tar en IConfiguration som indata. Konfigurationen måste vara begränsad till konfigurationsavsnittet för Kestrel.

ListenOptions.UseHttps

Konfigurera Kestrel att använda HTTPS.

ListenOptions.UseHttps tillägg:

  • UseHttps: Konfigurera Kestrel att använda HTTPS med standardcertifikatet. Utlöser ett undantag om inget standardcertifikat har konfigurerats.
  • 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 parametrar:

  • filename är sökvägen och filnamnet för en certifikatfil i förhållande till katalogen som innehåller appens innehållsfiler.
  • password är lösenordet som krävs för att komma åt X.509-certifikatdata.
  • configureOptions är en Action för att konfigurera HttpsConnectionAdapterOptions. Returnerar ListenOptions.
  • storeName är certifikatarkivet som certifikatet ska läsas in från.
  • subject är certifikatets ämnesnamn.
  • allowInvalid anger om ogiltiga certifikat ska beaktas, till exempel självsignerade certifikat.
  • location är lagringsplatsen som certifikatet ska läsas in från.
  • serverCertificate är X.509-certifikatet.

I produktion måste HTTPS konfigureras explicit. Som minst måste ett standardcertifikat tillhandahållas.

Konfigurationer som stöds beskrivs härnäst:

  • Ingen konfiguration
  • Ersätt standardcertifikatet från konfigurationen
  • Ändra standardvärdena i koden

Ingen konfiguration

Kestrel lyssnar på http://localhost:5000 och https://localhost:5001 (om ett standardcertifikat är tillgängligt).

Ersätt standardcertifikatet från konfigurationen

CreateDefaultBuilder anropar som standard Configure(context.Configuration.GetSection("Kestrel")) för att läsa in Kestrel konfiguration. Ett standardkonfigurationsschema för HTTPS-appinställningar är tillgängligt för Kestrel. Konfigurera flera slutpunkter, inklusive URL:er och certifikat som ska användas, antingen från en fil på disk eller från ett certifikatarkiv.

I följande appsettings.json exempel:

  • Ange AllowInvalid till true för att tillåta användning av ogiltiga certifikat (till exempel självsignerade certifikat).
  • Alla HTTPS-slutpunkter som inte anger ett certifikat (HttpsDefaultCert i exemplet nedan) återgår till certifikatet som definierats under Certifikat>Standard eller utvecklingscertifikatet.
{
  "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>"
      }
    }
  }
}

Ett alternativ till att använda Path och Password för alla certifikatnoder är att ange certifikatet med hjälp av certifikatarkivfält. Till exempel kan certifikat>standardcertifikat anges som:

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

Schemaanteckningar:

  • Slutpunkternas namn är inte skiftlägeskänsliga. Till exempel är HTTPS och Https giltiga.
  • Parametern Url krävs för varje slutpunkt. Formatet för den här parametern är samma som den översta Urls konfigurationsparametern, förutom att den är begränsad till ett enda värde.
  • Dessa slutpunkter ersätter de som definierats i den översta Urls konfigurationen i stället för att lägga till dem. Slutpunkter som definieras i kod via Listen är kumulativa med slutpunkterna som definieras i konfigurationsavsnittet.
  • Avsnittet Certificate är valfritt. Om det Certificate avsnittet inte anges används standardvärdena som definierats i tidigare scenarier. Om inga standardvärden är tillgängliga utlöser servern ett undantag och startar inte.
  • Avsnittet Certificate stöder både Path–Password och Subject–Store certifikat.
  • Valfritt antal slutpunkter kan definieras på det här sättet så länge de inte orsakar portkonflikter.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) returnerar en KestrelConfigurationLoader med en .Endpoint(string name, listenOptions => { }) metod som kan användas för att komplettera inställningarna för en konfigurerad slutpunkt:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader kan nås direkt för att fortsätta iterera på den befintliga inläsaren, till exempel den som tillhandahålls av CreateDefaultBuilder.

  • Konfigurationsavsnittet för varje slutpunkt finns på alternativen i metoden Endpoint så att anpassade inställningar kan läsas.
  • Flera konfigurationer kan läsas in genom att anropa options.Configure(context.Configuration.GetSection("{SECTION}")) igen med en annan sektion. Endast den senaste konfigurationen används, såvida inte Load uttryckligen anropas på tidigare instanser. Metapaketet anropar inte Load så att standardkonfigurationsavsnittet kan ersättas.
  • KestrelConfigurationLoader speglar Listen-familjen av API:er från KestrelServerOptions som överlagringar av Endpoint, så kod- och konfigurationsendpoints kan konfigureras på samma plats. Dessa överlagringar använder inte namn och använder bara standardinställningar från konfigurationen.

Ändra standardvärdena i kod

ConfigureEndpointDefaults och ConfigureHttpsDefaults kan användas för att ändra standardinställningarna för ListenOptions och HttpsConnectionAdapterOptions, inklusive att åsidosätta standardcertifikatet som angavs i föregående scenario. ConfigureEndpointDefaults och ConfigureHttpsDefaults ska anropas innan några slutpunkter konfigureras.

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

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

Kestrel stöd för SNI

servernamnindikering (SNI) kan användas för att vara värd för flera domäner på samma IP-adress och port. För att SNI ska fungera skickar klienten värdnamnet för den säkra sessionen till servern under TLS-handskakningen så att servern kan tillhandahålla rätt certifikat. Klienten använder det tillhandahållna certifikatet för krypterad kommunikation med servern under den säkra session som följer TLS-handskakningen.

Kestrel stöder SNI via ServerCertificateSelector callback-funktion. Återanropet anropas en gång per anslutning så att appen kan inspektera värdnamnet och välja lämpligt certifikat.

SNI-stöd kräver:

  • Körs på målramverk netcoreapp2.1 eller senare. Vid net461 eller senare anropas återanropet men name är alltid null. name är också null om klienten inte anger värdnamnsparametern i TLS-handskakningen.
  • Alla webbplatser körs på samma Kestrel instans. Kestrel stöder inte delning av en IP-adress och port över flera instanser utan omvänd 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;
            };
        });
    });
});

Anslutningsloggning

Anropa UseConnectionLogging för att skicka ut felsökningsloggar för kommunikation på byte-nivå för en anslutning. Anslutningsloggning är användbart för att felsöka problem med lågnivåkommunikation, till exempel under TLS-kryptering och bakom proxyservrar. Om UseConnectionLogging placeras före UseHttpsloggas krypterad trafik. Om UseConnectionLogging placeras efter UseHttpsloggas dekrypterad trafik.

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

Binda till en TCP-socket

Metoden Listen binder till en TCP-socket och en alternativ lambda tillåter X.509-certifikatkonfiguration:

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

Exemplet konfigurerar HTTPS för en slutpunkt med ListenOptions. Använd samma API för att konfigurera andra Kestrel inställningar för specifika slutpunkter.

I Windows kan självsignerade certifikat skapas med hjälp av New-SelfSignedCertificate PowerShell-cmdleten. För ett exempel som inte stöds, se UpdateIISExpressSSLForChrome.ps1.

På macOS, Linux och Windows kan certifikat skapas med OpenSSL-.

Binda till en Unix-socket

Lyssna på en Unix-socket med ListenUnixSocket för bättre prestanda med Nginx, som du ser i det här exemplet:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • I Nginx-konfigurationsfilen ska du ställa in posten server>location>proxy_pass till http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} är namnet på socketen som anges för ListenUnixSocket (till exempel kestrel-test.sock i föregående exempel).
  • Kontrollera att socketen kan skrivas av Nginx (till exempel chmod go+w /tmp/kestrel-test.sock).

Port 0

När portnumret 0 anges binder Kestrel dynamiskt till en tillgänglig port. Följande exempel visar hur du bestämmer vilken port Kestrel faktiskt är bunden till vid körning.

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

När appen körs anger konsolfönstrets utdata den dynamiska port där appen kan nås:

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

Begränsningar

Konfigurera slutpunkter med följande metoder:

  • UseUrls
  • --urls kommandoradsargument
  • urls värdkonfigurationsnyckel
  • ASPNETCORE_URLS miljövariabel

Dessa metoder är användbara för att få kod att fungera med andra servrar än Kestrel. Tänk dock på följande begränsningar:

  • HTTPS kan inte användas med dessa metoder om inte ett standardcertifikat anges i HTTPS-slutpunktskonfigurationen (till exempel med hjälp av KestrelServerOptions konfiguration eller en konfigurationsfil som visades tidigare i det här avsnittet).
  • När både Listen- och UseUrls-metoderna används samtidigt åsidosätter Listen slutpunkter UseUrls slutpunkter.

IIS-slutpunktskonfiguration

När du använder IIS anges URL-bindningar för IIS-åsidosättningsbindningar av antingen Listen eller UseUrls. Mer information finns i avsnittet ASP.NET Core Module.

ListenOptions.Protocols

Egenskapen Protocols upprättar HTTP-protokollen (HttpProtocols) som är aktiverade på en anslutningsslutpunkt eller för servern. Tilldela ett värde till egenskapen Protocols från HttpProtocols-uppräkningen.

HttpProtocols enum-värde Tillåten anslutningsprotokoll
Http1 endast HTTP/1.1. Kan användas med eller utan TLS.
Http2 Endast HTTP/2. Kan endast användas utan TLS om klienten stöder ett förhandskunskapsläge.
Http1AndHttp2 HTTP/1.1 och HTTP/2. HTTP/2 kräver att klienten väljer HTTP/2 i TLS Application-Layer Protocol Negotiation (ALPN) handskakning. Annars är anslutningen http/1.1 som standard.

Standardvärdet för ListenOptions.Protocols för en slutpunkt är HttpProtocols.Http1AndHttp2.

TLS-begränsningar för HTTP/2:

  • TLS version 1.2 eller senare
  • Omförhandling har deaktiverats
  • Komprimering har inaktiverats
  • Minsta tillfälliga nyckelutbytesstorlekar:
    • Elliptisk kurva Diffie-Hellman (ECDHE) [RFC4492]: minst 224 bitar
    • Begränsat fält Diffie-Hellman (DHE) [TLS12]: minst 2 048 bitar
  • Chiffersviten är inte förbjuden.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] med P-256 elliptisk kurva [FIPS186] stöds som standard.

I följande exempel tillåts HTTP/1.1- och HTTP/2-anslutningar på port 8000. Anslutningar skyddas av TLS med ett angivet certifikat:

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

Använd Anslutningsmellanprogram för att filtrera TLS-handskakningar per anslutning för specifika chiffer om det behövs.

I följande exempel utlöss NotSupportedException för alla chifferalgoritmer som appen inte stöder. Du kan också definiera och jämföra ITlsHandshakeFeature.CipherAlgorithm med en lista över acceptabla chiffersviter.

Ingen kryptering används med en ChifferAlgorithmType.Null chifferalgoritm.

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

Anslutningsfiltrering kan också konfigureras via en 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();
        });
    });
});

I Linux kan CipherSuitesPolicy användas för att filtrera TLS-handskakningar per anslutning:

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

Ange protokollet från konfigurationen

CreateDefaultBuilder anropar som standard serverOptions.Configure(context.Configuration.GetSection("Kestrel")) för att läsa in Kestrel konfiguration.

Följande appsettings.json exempel etablerar HTTP/1.1 som standardanslutningsprotokoll för alla slutpunkter:

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

Följande appsettings.json exempel etablerar HTTP/1.1-anslutningsprotokollet för en specifik slutpunkt:

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

Protokoll som anges i kod åsidosätter värden som anges av konfigurationen.

URL-prefixer

När du använder UseUrls, --urls kommandoradsargument, urls värdkonfigurationsnyckel eller ASPNETCORE_URLS miljövariabel kan URL-prefixen finnas i något av följande format.

Endast HTTP-URL-prefix är giltiga. Kestrel stöder inte HTTPS när du konfigurerar URL-bindningar med hjälp av UseUrls.

  • IPv4-adress med portnummer

    http://65.55.39.10:80/

    0.0.0.0 är ett specialfall som binder till alla IPv4-adresser.

  • IPv6-adress med portnummer

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

    [::] är IPv6-motsvarigheten till IPv4 0.0.0.0.

  • Värdnamn med portnummer

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

    Dessa värdnamn, *och +, är inte speciella. Allt som inte känns igen som en giltig IP-adress eller localhost kopplas till alla IPv4- och IPv6-adresser. Om du vill binda olika värdnamn till olika ASP.NET Core-appar på samma port använder du HTTP.sys eller en omvänd proxyserver, till exempel IIS, Nginx eller Apache.

    Varning

    Värdskap i en omvänd proxikonfiguration kräver vidarebefordrade huvudens mellanprogramskonfiguration.

  • Värdnamn localhost med portnummer eller loopback-IP-adress med portnummer

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

    När localhost anges försöker Kestrel binda till både IPv4- och IPv6-loopback-gränssnitt. Om den begärda porten används av en annan tjänst i något av loopback-gränssnitten kan Kestrel inte starta. Om något av loopback-gränssnittet inte är tillgängligt av någon annan anledning (oftast eftersom IPv6 inte stöds) loggar Kestrel en varning.

Värdfiltrering

Även om Kestrel stöder konfiguration baserat på prefix som http://example.com:5000ignorerar Kestrel till stor del värdnamnet. Värd localhost är ett specialfall som används för bindning till loopback-adresser. En annan värd än en explicit IP-adress binder till alla offentliga IP-adresser. Host rubriker valideras inte.

Som en lösning använder du Mellanprogram för värdfiltrering. Mellanprogram för värdfiltrering tillhandahålls av Microsoft.AspNetCore.HostFiltering-paketet, som implicit tillhandahålls för ASP.NET Core-appar. Mellanprogrammet läggs till av CreateDefaultBuilder, som anropar AddHostFiltering:

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

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

Mellanprogram för värdfiltrering är inaktiverat som standard. Om du vill aktivera mellanprogrammet definierar du en AllowedHosts nyckel i appsettings.json/appsettings.{Environment}.json. Värdet är en semikolonavgränsad lista med värdnamn utan portnummer:

appsettings.json:

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

Notera

Forwarded Headers Middleware har också ett AllowedHosts alternativ. Middleware för vidarebefordrade rubriker och middleware för värdfiltrering har liknande funktioner för olika scenarier. Det är lämpligt att ställa in AllowedHosts med mellanliggande programvara för vidarebefordrade huvuden när Host-huvudet inte bevaras vid vidarebefordran av begäranden med en omvänd proxyserver eller lastbalanserare. Det är lämpligt att ange AllowedHosts med mellanprogram för värdfiltrering när Kestrel används som en offentlig edge-server eller när Host-huvudet vidarebefordras direkt.

Mer information om vidarebefordrade huvudmellanprogram finns i Konfigurera ASP.NET Core att fungera med proxyservrar och lastbalanserare.

Libuv-transportkonfiguration

För projekt som kräver användning av Libuv (UseLibuv):

  • Lägg till ett beroende för Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv-paketet i appens projektfil:

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

  • Anropa UseLibuv på 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-begärandränering

Det är tidskrävande att öppna HTTP-anslutningar. För HTTPS är det också resursintensivt. Därför försöker Kestrel återanvända anslutningar enligt HTTP/1.1-protokollet. En begärandetext måste förbrukas fullt ut för att anslutningen ska kunna återanvändas. Appen använder inte alltid begärandekroppen, till exempel vid en POST-begäran där servern returnerar en omdirigering eller 404-svar. I fallet av POST-omdirigering:

  • Klienten kanske redan har skickat en del av POST data.
  • Servern skriver 301-svaret.
  • Anslutningen kan inte användas för en ny begäran förrän POST data från föregående begärandetext har lästs fullständigt.
  • Kestrel försöker tömma begärandetexten. Att tömma begärandetexten innebär att läsa och ta bort data utan att bearbeta dem.

Tömningsprocessen gör en kompromiss mellan att tillåta att anslutningen återanvänds och den tid det tar att tömma eventuella återstående data:

  • Tömning har en timeout på fem sekunder, vilket inte går att konfigurera.
  • Om alla data som anges av Content-Length- eller Transfer-Encoding-huvudet inte har lästs innan tidsgränsen stängs anslutningen.

Ibland kanske du vill avsluta begäran omedelbart, före eller efter att du har skrivit svaret. Klienter kan till exempel ha restriktiva datatak, så det kan vara en prioritet att begränsa uppladdade data. I sådana fall för att avsluta en begäran anropar du HttpContext.Abort från en kontrollant, Razor Page eller mellanprogram.

Det finns varningar för att anropa Abort:

  • Det kan vara långsamt och dyrt att skapa nya anslutningar.
  • Det finns ingen garanti för att klienten har läst svaret innan anslutningen stängs.
  • Att anropa Abort bör vara sällsynt och reserverat för allvarliga felfall, inte vanliga fel.
    • Anropa bara Abort när ett specifikt problem behöver lösas. Anropa till exempel Abort om skadliga klienter försöker POST data eller om det finns en bugg i klientkoden som orsakar stora eller många begäranden.
    • Anropa inte Abort för vanliga felsituationer, till exempel HTTP 404 (hittades inte).

Att anropa HttpResponse.CompleteAsync innan du anropar Abort ser till att servern har slutfört skrivning av svaret. Klientbeteendet är dock inte förutsägbart och de kanske inte läser svaret innan anslutningen avbryts.

Den här processen skiljer sig åt för HTTP/2 eftersom protokollet stöder avbrutna enskilda begärandeströmmar utan att stänga anslutningen. Den fem sekunder långa timeouten för avlopp gäller inte. Om det finns några olästa brödtextdata för begäranden när du har slutfört ett svar skickar servern en HTTP/2 RST-ram. Ytterligare dataramar för begärandetext ignoreras.

Om möjligt är det bättre för klienter att använda Expect: 100-continue begärandehuvud och vänta tills servern svarar innan begärandetexten börjar skickas. Det ger klienten möjlighet att undersöka svaret och avbryta innan de skickar onödiga data.

Ytterligare resurser