KestrelASP.NET Core'de web sunucusu uygulaması

Tom Dykstra, Chris Ross ve Stephen Halter tarafından

KestrelASP.NET Core için platformlar arası bir web sunucusudur. Kestrel, ASP.NET Core proje şablonlarında varsayılan olarak dahil edilen ve etkinleştirilen web sunucusudur.

Kestrel aşağıdaki senaryoları destekler:

  • HTTPS
  • HTTP/2 (macOS hariç†)
  • WebSockets'i etkinleştirmek için kullanılan opak yükseltme
  • Nginx'in arkasında yüksek performans için Unix yuvaları

†HTTP/2, gelecek bir sürümde macOS'ta desteklenecektir.

Kestrel , .NET Core'un desteklediği tüm platformlarda ve sürümlerde desteklenir.

Kullanmaya başlayın

ASP.NET Core proje şablonları IIS ile barındırılmadığında varsayılan olarak kullanırKestrel. Aşağıdaki şablon tarafından oluşturulan Program.csWebApplication.CreateBuilder içinde yöntemi dahili olarak çağrı yaparUseKestrel:

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

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

app.Run();

ve WebApplicationBuilderyapılandırma WebApplication hakkında daha fazla bilgi için bkz. Minimum API'lere genel bakış.

İsteğe bağlı istemci sertifikaları

Sertifika ile uygulamanın bir alt kümesini koruması gereken uygulamalar hakkında bilgi için bkz . İsteğe bağlı istemci sertifikaları.

Ek kaynaklar

Not

ASP.NET Core 5.0 itibarıyla libuv Kestreltaşıması kullanımdan kalkmıştı. Libuv aktarımı, Windows ARM64 gibi yeni işletim sistemi platformlarını destekleyecek güncelleştirmeleri almaz ve gelecek bir sürümde kaldırılacaktır. Kullanılmayan UseLibuv yönteme yapılan çağrıları kaldırın ve bunun yerine varsayılan Yuva aktarımını kullanın Kestrel.

KestrelASP.NET Core için platformlar arası bir web sunucusudur. Kestrel, ASP.NET Core proje şablonlarında varsayılan olarak dahil edilen ve etkinleştirilen web sunucusudur.

Kestrel aşağıdaki senaryoları destekler:

  • HTTPS
  • HTTP/2 (macOS hariç†)
  • WebSockets'i etkinleştirmek için kullanılan opak yükseltme
  • Nginx'in arkasında yüksek performans için Unix yuvaları

†HTTP/2, gelecek bir sürümde macOS'ta desteklenecektir.

Kestrel , .NET Core'un desteklediği tüm platformlarda ve sürümlerde desteklenir.

Örnek kodu görüntüleme veya indirme (indirme)

Kullanmaya başlayın

ASP.NET Core proje şablonları IIS ile barındırılmadığında varsayılan olarak kullanırKestrel. içinde Program.csyöntemi şunu ConfigureWebHostDefaults çağırır UseKestrel:

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

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

Konağı oluşturma hakkında daha fazla bilgi için ASP.NET Core'da .NET Genel Ana Bilgisayarı'nın Konakayarlama ve Varsayılan oluşturucu ayarları bölümlerine bakın.

İsteğe bağlı istemci sertifikaları

Sertifika ile uygulamanın bir alt kümesini koruması gereken uygulamalar hakkında bilgi için bkz . İsteğe bağlı istemci sertifikaları.

Ek kaynaklar

Not

ASP.NET Core 5.0 itibarıyla libuv Kestreltaşıması kullanımdan kalkmıştı. Libuv aktarımı, Windows ARM64 gibi yeni işletim sistemi platformlarını destekleyecek güncelleştirmeleri almaz ve gelecek bir sürümde kaldırılacaktır. Kullanılmayan UseLibuv yönteme yapılan çağrıları kaldırın ve bunun yerine varsayılan Yuva aktarımını kullanın Kestrel.

KestrelASP.NET Core için platformlar arası bir web sunucusudur. Kestrelvarsayılan olarak ASP.NET Core proje şablonlarına dahil edilen web sunucusudur.

Kestrel aşağıdaki senaryoları destekler:

  • HTTPS
  • WebSockets'i etkinleştirmek için kullanılan opak yükseltme
  • Nginx'in arkasında yüksek performans için Unix yuvaları
  • HTTP/2 (macOS hariç†)

†HTTP/2, gelecek bir sürümde macOS'ta desteklenecektir.

Kestrel , .NET Core'un desteklediği tüm platformlarda ve sürümlerde desteklenir.

Örnek kodu görüntüleme veya indirme (indirme)

HTTP/2 desteği

Http/2, aşağıdaki temel gereksinimler karşılanırsa ASP.NET Core uygulamalarda kullanılabilir:

  • İşletim sistemi†
    • Windows Server 2016/Windows 10 veya üzeri‡
    • OpenSSL 1.0.2 veya üzeri yüklü Linux (örneğin, Ubuntu 16.04 veya üzeri)
  • Hedef çerçeve: .NET Core 2.2 veya üzeri
  • Uygulama Katmanı Protokolü Anlaşması (ALPN) bağlantısı
  • TLS 1.2 veya üzeri bağlantı

†HTTP/2, gelecek bir sürümde macOS'ta desteklenecektir. Kestrel‡ Windows Server 2012 R2 ve Windows 8.1 üzerinde HTTP/2 için sınırlı desteğe sahiptir. Bu işletim sistemlerinde kullanılabilen desteklenen TLS şifreleme paketlerinin listesi sınırlı olduğundan destek sınırlıdır. TLS bağlantılarının güvenliğini sağlamak için Eliptik Eğri Dijital İmza Algoritması (ECDSA) kullanılarak oluşturulan bir sertifika gerekebilir.

HTTP/2 bağlantısı kuruluysa, HttpRequest.Protocol bildirir HTTP/2.

.NET Core 3.0'dan itibaren HTTP/2 varsayılan olarak etkindir. Yapılandırma hakkında daha fazla bilgi için seçenekler ve ListenOptions.Protocols bölümlerine bakınKestrel.

Ters ara sunucu ile ne zaman kullanılır Kestrel ?

Kestrel tek başına veya ters ara sunucu ile kullanılabilir. Ters ara sunucu ağdan HTTP istekleri alır ve bunları adresine Kestreliletir. Ters ara sunucu örnekleri şunlardır:

Kestrel uç (İnternet'e yönelik) web sunucusu olarak kullanılır:

Kestrel ters proxy sunucusu olmadan İnternet ile doğrudan iletişim kurar

Kestrel ters ara sunucu yapılandırmasında kullanılır:

Kestrel IIS, Nginx veya Apache gibi bir ters ara sunucu aracılığıyla İnternet ile dolaylı olarak iletişim kurar

Ters proxy sunucusu olan veya olmayan yapılandırma, desteklenen bir barındırma yapılandırmasıdır.

Kestrel ters proxy sunucusu olmayan bir uç sunucu olarak kullanıldığında, aynı IP'nin ve bağlantı noktasının birden çok işlem arasında paylaşılması desteklenmez. Bir bağlantı noktasında dinleyecek şekilde yapılandırıldığında Kestrel , Kestrel isteklerin Host üst bilgilerinden bağımsız olarak söz konusu bağlantı noktasının tüm trafiğini işler. Bağlantı noktalarını paylaşabilen ters ara sunucu, istekleri benzersiz bir IP ve bağlantı noktası üzerinden adresine Kestrel iletebilir.

Ters ara sunucu gerekli olmasa bile, ters ara sunucu kullanmak iyi bir seçim olabilir.

Ters ara sunucu:

  • Barındırdığını uygulamaların kullanıma sunulan genel yüzey alanını sınırlayabilir.
  • Ek bir yapılandırma ve savunma katmanı sağlayın.
  • Mevcut altyapıyla daha iyi tümleştirebilir.
  • Yük dengeleme ve güvenli iletişim (HTTPS) yapılandırmasını basitleştirin. Yalnızca ters proxy sunucusu bir X.509 sertifikası gerektirir ve bu sunucu düz HTTP kullanarak iç ağdaki uygulamanın sunucularıyla iletişim kurabilir.

Uyarı

Ters ara sunucu yapılandırmasında barındırmak için İletilen Üst Bilgiler Ara Yazılımı yapılandırması gerekir.

KestrelASP.NET Core uygulamalarında

ASP.NET Core proje şablonları varsayılan olarak kullanırKestrel. içinde Program.csyöntemi şunu ConfigureWebHostDefaults çağırır UseKestrel:

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

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

Konağı oluşturma hakkında daha fazla bilgi için ASP.NET Core'da .NET Genel Ana Bilgisayarı'nın Konakayarlama ve Varsayılan oluşturucu ayarları bölümlerine bakın.

çağrısı ConfigureWebHostDefaultsyaptıktan sonra ek yapılandırma sağlamak için kullanın 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 Seçenekler

Web Kestrel sunucusu, özellikle İnternet'e yönelik dağıtımlarda yararlı olan kısıtlama yapılandırma seçeneklerine sahiptir.

sınıfının özelliğinde LimitsKestrelServerOptions kısıtlamalar ayarlayın. Limits özelliği sınıfının bir örneğini barındırıyorKestrelServerLimits.

Aşağıdaki örneklerde ad alanı Microsoft.AspNetCore.Server.Kestrel.Core kullanılır:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Bu makalenin devamında gösterilen örneklerde, Kestrel seçenekler C# kodunda yapılandırılır. Kestrel seçenekleri bir yapılandırma sağlayıcısı kullanılarak da ayarlanabilir. Örneğin, Dosya Yapılandırma Sağlayıcısı yapılandırmayı bir appsettings.json veya appsettings.{Environment}.json dosyasından yükleyebilirKestrel:

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

Not

KestrelServerOptions ve uç nokta yapılandırması, yapılandırma sağlayıcılarından yapılandırılabilir. Kalan Kestrel yapılandırma C# kodunda yapılandırılmalıdır.

Aşağıdaki yaklaşımlardan birini kullanın:

  • içinde Startup.ConfigureServicesyapılandırınKestrel:

    1. sınıfına öğesinin IConfiguration bir örneğini Startup ekleme. Aşağıdaki örnekte, eklenen yapılandırmanın özelliğine Configuration atandığı varsayılır.

    2. içinde Startup.ConfigureServices, yapılandırmanın Kestrel bölümünü 'nin yapılandırmasına Kestrelyükleyin:

      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)
          {
              ...
          }
      }
      
  • Konağı oluştururken yapılandırın Kestrel :

    içinde Program.cs, yapılandırmanın Kestrel bölümünü 'nin yapılandırmasına Kestrelyükleyin:

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

Yukarıdaki yaklaşımların her ikisi de herhangi bir yapılandırma sağlayıcısıyla çalışır.

Etkin tutma zaman aşımı

KeepAliveTimeout

Etkin tutma zaman aşımını alır veya ayarlar. Varsayılan olarak 2 dakikadır.

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

En fazla istemci bağlantısı

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Uygulamanın tamamı için en fazla eşzamanlı açık TCP bağlantısı sayısı aşağıdaki kodla ayarlanabilir:

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

HTTP veya HTTPS'den başka bir protokole (örneğin, bir WebSockets isteğine) yükseltilen bağlantılar için ayrı bir sınır vardır. Bağlantı yükseltildikten sonra sınıra MaxConcurrentConnections göre sayılmaz.

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

En fazla bağlantı sayısı varsayılan olarak sınırsızdır (null).

İstek gövdesi boyutu üst sınırı

MaxRequestBodySize

Varsayılan maksimum istek gövdesi boyutu 30.000.000 bayttır ve bu da yaklaşık 28,6 MB'tır.

ASP.NET Core MVC uygulamasında sınırı geçersiz kılmak için önerilen yaklaşım, özniteliğini RequestSizeLimitAttribute bir eylem yönteminde kullanmaktır:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Her istekte uygulama kısıtlamasının nasıl yapılandırıldığını gösteren bir örnek aşağıda verilmiştir:

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

Ara yazılımda belirli bir istekte ayarı geçersiz kılın:

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

Uygulama isteği okumaya başladıktan sonra istekte sınırı yapılandırırsa bir özel durum oluşur. Özelliğin salt okunur durumda olup olmadığını MaxRequestBodySize belirten bir IsReadOnly özellik vardır; bu da sınırı yapılandırmak için çok geç olduğu anlamına gelir.

Bir uygulama ASP.NET Core Modülüarkasında işlem dışı bırakıldığında, KestrelIIS sınırı zaten ayarladığı için istek gövdesi boyut sınırı devre dışı bırakılır.

Minimum istek gövdesi veri hızı

MinRequestBodyDataRate MinResponseDataRate

Kestrel verilerin bayt/saniye cinsinden belirtilen hızda ulaşıp varmadığını her saniye denetler. Hız minimum değerin altına düşerse, bağlantı zaman aşımına ulanır. Yetkisiz kullanım süresi, istemcinin gönderme oranını en düşük değere kadar artırmasını sağlayan Kestrel süredir; bu süre boyunca oran denetlenmiyor. Yetkisiz kullanım süresi, TCP yavaş başlatma nedeniyle başlangıçta yavaş hızda veri gönderen bağlantıların bırakılmasını önlemeye yardımcı olur.

Varsayılan en düşük hız, 5 saniyelik yetkisiz kullanım süresiyle 240 bayt/saniyedir.

Minimum oran yanıt için de geçerlidir. İstek sınırını ve yanıt sınırını ayarlama kodu, özellik ve arabirim adlarında veya Response olması RequestBody dışında aynıdır.

Aşağıda, içinde en düşük veri oranlarının nasıl yapılandırıldığını gösteren bir örnek verilmiştir 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);
})

Ara yazılımda istek başına en düşük hız sınırlarını geçersiz kılın:

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

Protokolün IHttpMinResponseDataRateFeature istek çoğullama desteği nedeniyle http/2 için genellikle istek başına hız sınırlarının değiştirilmesi desteklenmediğinden, önceki örnekte başvurulen http/2 isteklerinde mevcut HttpContext.Features değildir. Ancak, IHttpMinRequestBodyDataRateFeatureHttpContext.Features okuma hızı sınırı bir HTTP/2 isteği için eşit olarak ayarlanarak IHttpMinRequestBodyDataRateFeature.MinDataRatenull istek başına tamamen devre dışı bırakılabildiği için HTTP/2 istekleri için hala mevcuttur. Bunu okumaya IHttpMinRequestBodyDataRateFeature.MinDataRate veya başka null bir değere ayarlamaya çalışmak, bir HTTP/2 isteği verilmesiyle sonuçlanır NotSupportedException .

aracılığıyla KestrelServerOptions.Limits yapılandırılan sunucu genelinde hız sınırları, hem HTTP/1.x hem de HTTP/2 bağlantıları için geçerli olmaya devam eder.

İstek üst bilgileri zaman aşımı

RequestHeadersTimeout

Sunucunun istek üst bilgilerini almak için harcadığı maksimum süreyi alır veya ayarlar. Varsayılan değer 30 saniyedir.

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

Bağlantı başına en fazla akış sayısı

Http2.MaxStreamsPerConnection HTTP/2 bağlantısı başına eş zamanlı istek akışlarının sayısını sınırlar. Fazla akışlar reddedilir.

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

Varsayılan değer 100’dür.

Üst bilgi tablosu boyutu

HPACK kod çözücüsü HTTP/2 bağlantıları için HTTP üst bilgilerini açar. Http2.HeaderTableSize HPACK kod çözücünün kullandığı üst bilgi sıkıştırma tablosunun boyutunu sınırlar. Değer sekizli olarak sağlanır ve sıfırdan (0) büyük olmalıdır.

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

Varsayılan değer 4096'dır.

En büyük çerçeve boyutu

Http2.MaxFrameSize sunucu tarafından alınan veya gönderilen HTTP/2 bağlantı çerçevesi yükünün izin verilen en büyük boyutunu gösterir. Değer sekizli olarak sağlanır ve 2^14 (16.384) ile 2^24-1 (16.777.215) arasında olmalıdır.

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

Varsayılan değer 2^14 'tür (16.384).

En büyük istek üst bilgisi boyutu

Http2.MaxRequestHeaderFieldSize , istek üst bilgi değerlerinin sekizlisinde izin verilen en büyük boyutu gösterir. Bu sınır, sıkıştırılmış ve sıkıştırılmamış gösterimlerindeki ad ve değer için geçerlidir. Değer sıfırdan (0) büyük olmalıdır.

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

Varsayılan değer 8.192'dir.

İlk bağlantı penceresi boyutu

Http2.InitialConnectionWindowSize sunucu arabelleklerinin bağlantı başına tüm istekler (akışlar) arasında bir kerede toplanmış bayt cinsinden istek gövdesi verilerinin üst sınırını gösterir. İstekler ile de sınırlıdır Http2.InitialStreamWindowSize. Değer 65.535'ten büyük veya buna eşit ve 2^31'den küçük olmalıdır (2.147.483.648).

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

Varsayılan değer 128 KB'tır (131.072).

İlk akış penceresi boyutu

Http2.InitialStreamWindowSize , sunucu arabelleklerinin istek başına bir kerede (akış) bayt cinsinden istek gövdesi verilerinin üst sınırını gösterir. İstekler de ile Http2.InitialConnectionWindowSizesınırlıdır. Değer 65.535'ten büyük veya buna eşit ve 2^31'den küçük olmalıdır (2.147.483.648).

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

Varsayılan değer 96 KB'tır (98.304).

Römork

HTTP Fragmanları HTTP Üst Bilgilerine benzer, ancak yanıt gövdesi gönderildikten sonra gönderilir. IIS ve HTTP.sys için yalnızca HTTP/2 yanıt fragmanları desteklenir.

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

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

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

Yukarıdaki örnek kodda:

  • SupportsTrailers , römorkların yanıt için desteklendiğini güvence altına alır.
  • DeclareTrailer verilen römork adını yanıt üst bilgisine Trailer ekler. Yanıtın fragmanlarını bildirmek isteğe bağlıdır ancak önerilir. çağrılırsa DeclareTrailer , yanıt üst bilgileri gönderilmeden önce olmalıdır.
  • AppendTrailer römorku ekler.

Sıfırla

Sıfırlama, sunucunun belirtilen hata koduyla bir HTTP/2 isteğini sıfırlamasına olanak tanır. Sıfırlama isteğinin durduruldu olduğu kabul edilir.

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

Reset yukarıdaki kod örneğinde hata kodunu belirtir INTERNAL_ERROR . HTTP/2 hata kodları hakkında daha fazla bilgi için HTTP/2 belirtimi hata kodu bölümünü ziyaret edin.

Zaman Uyumlu G/Ç

AllowSynchronousIO istek ve yanıt için zaman uyumlu G/Ç'ye izin verilip verilmeyeceğini denetler. false varsayılan değerdir.

Uyarı

Zaman uyumlu G/Ç işlemlerinin çok sayıda engellenmesi, iş parçacığı havuzu aç kalmasına neden olabilir ve bu da uygulamanın yanıt vermemesine neden olabilir. Yalnızca zaman uyumsuz G/Ç'yi desteklemeyen bir kitaplık kullanırken etkinleştirin AllowSynchronousIO .

Aşağıdaki örnek zaman uyumlu G/Ç'yi etkinleştirir:

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

Diğer Kestrel seçenekler ve sınırlar hakkında bilgi için bkz:

Uç nokta yapılandırması

Varsayılan olarak, ASP.NET Core şu şekilde bağlanır:

  • http://localhost:5000
  • https://localhost:5001 (yerel geliştirme sertifikası mevcut olduğunda)

Url'leri belirtmek için şunları kullanın:

  • ASPNETCORE_URLS ortam değişkeni.
  • --urls komut satırı bağımsız değişkeni.
  • urls ana bilgisayar yapılandırma anahtarı.
  • UseUrls uzantı yöntemi.

Bu yaklaşımlar kullanılarak sağlanan değer bir veya daha fazla HTTP ve HTTPS uç noktası (varsayılan sertifika varsa HTTPS) olabilir. Değeri noktalı virgülle ayrılmış liste (örneğin, "Urls": "http://localhost:8000;http://localhost:8001") olarak yapılandırın.

Bu yaklaşımlar hakkında daha fazla bilgi için bkz . Sunucu URL'leri ve Geçersiz kılma yapılandırması.

Geliştirme sertifikası oluşturulur:

Bazı tarayıcılar, yerel geliştirme sertifikasına güvenmek için açık izin verilmesini gerektirir.

Proje şablonları, uygulamaları varsayılan olarak HTTPS üzerinde çalışacak şekilde yapılandırıp HTTPS yeniden yönlendirme ve HSTS desteği içerir.

için URL ön eklerini KestrelServerOptions ve bağlantı noktalarını yapılandırmak için Kestrelçağrısı Listen veya ListenUnixSocket yöntemleri açın.

UseUrls--urls, komut satırı bağımsız değişkeni, urls konak yapılandırma anahtarı ve ASPNETCORE_URLS ortam değişkeni de çalışır, ancak bu bölümün ilerleyen bölümlerinde belirtilen sınırlamalara sahiptir (HTTPS uç noktası yapılandırması için varsayılan bir sertifika sağlanmalıdır).

KestrelServerOptions konfigürasyon:

ConfigureEndpointDefaults(Eylem<DinleyicisiSeçenekler>)

Belirtilen her uç nokta için çalıştırılacak yapılandırmayı Action belirtir. Birden çok kez çağrılması ConfigureEndpointDefaults , öncekilerin Actionyerine son Action belirtilen değeri ekler.

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

Not

Çağrıdan önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.ConfigureEndpointDefaults

YapılandırHttpsDefaults(Eylem<HttpsConnectionAdapterOptions>)

Her HTTPS uç noktası için çalıştırılacak yapılandırmayı Action belirtir. Birden çok kez çağrılması ConfigureHttpsDefaults , öncekilerin Actionyerine son Action belirtilen değeri ekler.

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

Not

Çağrıdan önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.ConfigureHttpsDefaults

Configure(IConfiguration)

Ayarlama için Kestrel giriş olarak alan bir IConfiguration yapılandırma yükleyicisi oluşturur. Yapılandırmanın kapsamı için Kestrelyapılandırma bölümünün kapsamına alınması gerekir.

ListenOptions.UseHttps

HTTPS kullanmak için yapılandırın Kestrel .

ListenOptions.UseHttps Uzantı -ları:

  • UseHttps: HTTPS'yi varsayılan sertifikayla kullanacak şekilde yapılandırın Kestrel . Varsayılan sertifika yapılandırılmamışsa özel durum oluşturur.
  • 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 Parametre:

  • filename , uygulamanın içerik dosyalarını içeren dizine göre bir sertifika dosyasının yolu ve dosya adıdır.
  • password , X.509 sertifika verilerine erişmek için gereken paroladır.
  • configureOptions , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. döndürür ListenOptions.
  • storeName , sertifikanın yüklendiği sertifika deposudur.
  • subject sertifikanın konu adıdır.
  • allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
  • location , sertifikanın yüklenip yüklenemediklerinin depo konumudur.
  • serverCertificate X.509 sertifikasıdır.

Üretimde HTTPS açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

Desteklenen yapılandırmalar aşağıda açıklanmıştır:

  • Yapılandırma yok
  • Varsayılan sertifikayı yapılandırmadan değiştirme
  • Koddaki varsayılanları değiştirme

Yapılandırma yok

Kestrelve https://localhost:5001 (http://localhost:5000varsayılan bir sertifika varsa) dinler.

Varsayılan sertifikayı yapılandırmadan değiştirme

CreateDefaultBuilderyapılandırmayı yüklemek Kestrel için varsayılan olarak çağrılarConfigure(context.Configuration.GetSection("Kestrel")). için Kestrelvarsayılan BIR HTTPS uygulama ayarları yapılandırma şeması sağlanır. Disk üzerindeki bir dosyadan veya bir sertifika deposundan URL'ler ve kullanılacak sertifikalar dahil olmak üzere birden çok uç nokta yapılandırın.

Aşağıdaki appsettings.json örnekte:

  • Geçersiz sertifikaların (örneğin, otomatik olarak imzalanan sertifikalar) kullanılmasına izin vermek için AllowInvalidtrue olarak ayarlayın.
  • Sertifika belirtmeyen herhangi bir HTTPS uç noktası (aşağıdaki örnekte HttpsDefaultCert), Sertifika Varsayılanı> veya geliştirme sertifikası altında tanımlanan sertifikaya geri döner.
{
  "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>"
      }
    }
  }
}

Herhangi bir sertifika düğümü için Yol ve Parola kullanmanın bir alternatifi, sertifika depolama alanlarını kullanarak sertifikayı belirtmektir. Örneğin, Sertifikalar>Varsayılan sertifikası şu şekilde belirtilebilir:

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

Şema notları:

  • Uç nokta adları büyük/küçük harfe duyarlı değildir. Örneğin ve HTTPSHttps geçerlidir.
  • Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında en üst düzey Urls yapılandırma parametresiyle aynıdır.
  • Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
  • Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, önceki senaryolarda tanımlanan varsayılanlar kullanılır. Varsayılan değer yoksa, sunucu bir özel durum oluşturur ve başlatılamaz.
  • bölümü Certificate hem Yol-Parola hem de Konu-Depolama sertifikalarını destekler.
  • Bağlantı noktası çakışmalarına neden olmayan herhangi bir sayıda uç nokta bu şekilde tanımlanabilir.
  • options.Configure(context.Configuration.GetSection("{SECTION}"))KestrelConfigurationLoader, yapılandırılmış bir .Endpoint(string name, listenOptions => { }) uç noktanın ayarlarını desteklemek için kullanılabilecek bir yöntemiyle döndürür:
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader , tarafından CreateDefaultBuildersağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

  • Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemdeki Endpoint seçeneklerde kullanılabilir.
  • Başka bir bölümle yeniden çağrılarak options.Configure(context.Configuration.GetSection("{SECTION}")) birden çok yapılandırma yüklenebilir. Önceki örneklerde açıkça çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Meta paket, varsayılan yapılandırma bölümünün değiştirilebilmesi için çağrı Load yapmaz.
  • KestrelConfigurationLoaderListen API'lerin KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Koddaki varsayılanları değiştirme

ConfigureEndpointDefaultsve ConfigureHttpsDefaults önceki senaryoda belirtilen varsayılan sertifikayı geçersiz kılma dahil olmak üzere ve HttpsConnectionAdapterOptionsiçin varsayılan ayarları değiştirmek için ListenOptions kullanılabilir. ConfigureEndpointDefaults ve ConfigureHttpsDefaults herhangi bir uç nokta yapılandırılmadan önce çağrılmalıdır.

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

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

Kestrel SNI desteği

Sunucu Adı Göstergesi (SNI), aynı IP adresi ve bağlantı noktasında birden çok etki alanını barındırmak için kullanılabilir. SNI'nin çalışması için istemci, sunucunun doğru sertifikayı sağlayabilmesi için TLS el sıkışması sırasında güvenli oturum için ana bilgisayar adını sunucuya gönderir. İstemci, TLS el sıkışmasını izleyen güvenli oturum sırasında sunucuyla şifreli iletişim için mobilyalı sertifikayı kullanır.

Kestrel geri çağırma yoluyla SNI'yi ServerCertificateSelector destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı seçmesine izin vermek için her bağlantı için geri arama bir kez çağrılır.

SNI desteği şunları gerektirir:

  • Hedef çerçevede veya daha sonraki sürümlerde netcoreapp2.1 çalıştırılıyor. Veya net461 daha sonra geri arama çağrılır, ancak name her zaman nullolur. name ayrıca null istemcinin TLS el sıkışmasında ana bilgisayar adı parametresini sağlamamasıdır.
  • Tüm web siteleri aynı Kestrel örnekte çalışır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.
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;
            };
        });
    });
});

Bağlantı günlüğü

Bağlantıda bayt düzeyi iletişim için Hata ayıklama düzeyi günlüklerini yaymak için çağrısı UseConnectionLogging yapın. Bağlantı günlüğü, TLS şifrelemesi sırasında ve ara sunucuların arkasında olduğu gibi alt düzey iletişim sorunlarını gidermek için yararlıdır. önüne UseHttpsyerleştirilirse UseConnectionLogging şifrelenmiş trafik günlüğe kaydedilir. sonra yerleştirilirse UseConnectionLoggingUseHttps, şifresi çözülen trafik günlüğe kaydedilir.

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

TCP yuvasına bağlama

Listen yöntemi bir TCP yuvasına bağlanır ve lambda seçenekleri X.509 sertifika yapılandırmasına izin verir:

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

Örnek, ile ListenOptionsbir uç nokta için HTTPS'yi yapılandırıyor. Belirli uç noktaların diğer Kestrel ayarlarını yapılandırmak için aynı API'yi kullanın.

Windows'da otomatik olarak imzalanan sertifikalar PowerShell cmdlet'iNew-SelfSignedCertificate kullanılarak oluşturulabilir. Desteklenmeyen bir örnek için bkz UpdateIISExpressSSLForChrome.ps1. .

macOS, Linux ve Windows'da , OpenSSL kullanılarak sertifikalar oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket dinleyin:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • Nginx yapılandırma dosyasında girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET}, (örneğin, kestrel-test.sock önceki örnekte) sağlanan ListenUnixSocket yuvanın adıdır.
  • Yuvanın Nginx tarafından yazılabilir olduğundan emin olun (örneğin, chmod go+w /tmp/kestrel-test.sock).

Bağlantı noktası 0

Bağlantı noktası numarası 0 belirtildiğinde, Kestrel kullanılabilir bir bağlantı noktasına dinamik olarak bağlanır. Aşağıdaki örnekte çalışma zamanında hangi bağlantı noktasının Kestrel gerçekten bağlandığının nasıl belirleneceği gösterilmektedir:

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

Uygulama çalıştırıldığında konsol penceresi çıkışı, uygulamaya ulaşabileceğiniz dinamik bağlantı noktasını gösterir:

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

Sınırlamalar

Uç noktaları aşağıdaki yaklaşımlarla yapılandırın:

  • UseUrls
  • --urls komut satırı bağımsız değişkeni
  • urls konak yapılandırma anahtarı
  • ASPNETCORE_URLS ortam değişkeni

Bu yöntemler, dışındaki Kestrelsunucularla kod çalışması için yararlıdır. Ancak aşağıdaki sınırlamalara dikkat edin:

  • HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlanmadığı sürece HTTPS bu yaklaşımlarla kullanılamaz (örneğin, bu konuda daha önce gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanma KestrelServerOptions ).
  • Hem hem de Listen yaklaşımları aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.UseUrls

IIS uç noktası yapılandırması

IIS kullanırken, IIS geçersiz kılma bağlamaları için URL bağlamaları veya UseUrlstarafından Listen ayarlanır. Daha fazla bilgi için ASP.NET Core Modülü konusuna bakın.

ListenOptions.Protocols

özelliği, Protocols bir bağlantı uç noktasında veya sunucu için etkinleştirilen HTTP protokollerini (HttpProtocols) oluşturur. Enum'dan özelliğine Protocols bir değer atayın HttpProtocols .

HttpProtocols sabit listesi değeri Bağlantı protokolüne izin verilir
Http1 Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
Http2 Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa kullanılabilir.
Http1AndHttp2 HTTP/1.1 ve HTTP/2. HTTP/2, istemcinin TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışmasında HTTP/2'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olarak ayarlanır.

Herhangi bir uç nokta için varsayılan ListenOptions.Protocols değer şeklindedir HttpProtocols.Http1AndHttp2.

HTTP/2 için TLS kısıtlamaları:

  • TLS sürüm 1.2 veya üzeri
  • Yeniden anlaşma devre dışı bırakıldı
  • Sıkıştırma devre dışı
  • Minimum kısa ömürlü anahtar değişimi boyutları:
    • Elips eğrisi Diffie-Hellman (ECDHE) [RFC4492]: En az 224 bit
    • Sonlu alan Diffie-Hellman (DHE) [TLS12]: En az 2048 bit
  • Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta eğrisi [FIPS186] varsayılan olarak desteklenir.

Aşağıdaki örnek, 8000 numaralı bağlantı noktasında HTTP/1.1 ve HTTP/2 bağlantılarına izin verir. Bağlantıların güvenliği SAĞLANAN bir sertifikayla TLS tarafından sağlanır:

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

Gerekirse, TLS el sıkışmalarını belirli şifreler için bağlantı temelinde filtrelemek için Bağlantı Ara Yazılımı'nı kullanın.

Aşağıdaki örnek, uygulamanın desteklemediği herhangi bir şifreleme algoritması için oluşturur NotSupportedException . Alternatif olarak, ITlsHandshakeFeature.CipherAlgorithm öğesini tanımlayıp kabul edilebilir şifre paketlerinin listesiyle karşılaştırın.

CipherAlgorithmType.Null şifreleme algoritması ile şifreleme kullanılmaz.

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

Bağlantı filtreleme bir IConnectionBuilder lambda aracılığıyla da yapılandırılabilir:

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

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına temelinde filtrelemek için kullanılabilir:

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

Yapılandırmadan protokolü ayarlama

CreateDefaultBuilderyapılandırmayı yüklemek Kestrel için varsayılan olarak çağrılarserverOptions.Configure(context.Configuration.GetSection("Kestrel")).

Aşağıdaki appsettings.json örnek, tüm uç noktalar için varsayılan bağlantı protokolü olarak HTTP/1.1'i oluşturur:

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

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Kod geçersiz kılma değerlerinde belirtilen protokoller yapılandırmaya göre ayarlanır.

URL ön ekleri

, --urls komut satırı bağımsız değişkeni, urls konak yapılandırma anahtarı veya ASPNETCORE_URLS ortam değişkeni kullanılırkenUseUrls, URL ön ekleri aşağıdaki biçimlerden herhangi birinde olabilir.

Yalnızca HTTP URL ön ekleri geçerlidir. Kestrel kullanarak UseUrlsURL bağlamalarını yapılandırırken HTTPS'yi desteklemez.

  • Bağlantı noktası numarasına sahip IPv4 adresi

    http://65.55.39.10:80/
    

    0.0.0.0 , tüm IPv4 adreslerine bağlanan özel bir durumdur.

  • Bağlantı noktası numarasına sahip IPv6 adresi

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

    [::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.

  • Bağlantı noktası numarasına sahip ana bilgisayar adı

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

    Ana bilgisayar adları , *ve +özel değildir. Geçerli bir IP adresi olarak tanınmayan veya localhost tüm IPv4 ve IPv6 IP'lerine bağlanan her şey. Farklı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya IIS, Nginx veya Apache gibi bir ters ara sunucu kullanın.

    Uyarı

    Ters ara sunucu yapılandırmasında barındırmak için İletilen Üst Bilgiler Ara Yazılımı yapılandırması gerekir.

  • Bağlantı noktası numarasıyla ana bilgisayar localhost adı veya bağlantı noktası numarasıyla geri döngü IP'si

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

    Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Herhangi bir nedenle geri döngü arabirimi kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

Konak filtreleme

gibi http://example.com:5000Kestrel ön ekleri temel alan yapılandırmayı desteklese Kestrel de, konak adını büyük ölçüde yoksayar. Konak localhost , geri döngü adreslerine bağlama için kullanılan özel bir durumdur. Açık IP adresi dışındaki tüm konaklar tüm genel IP adreslerine bağlanır. Host üst bilgiler doğrulanmaz.

Geçici bir çözüm olarak, Konak Filtreleme Ara Yazılımını kullanın. Konak Filtreleme Ara Yazılımı, ASP.NET Core uygulamaları için örtük olarak sağlanan Microsoft.AspNetCore.HostFiltering paketi tarafından sağlanır. Ara yazılım tarafından eklenir CreateDefaultBuilderve öğesini çağırır 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>();
}

Konak Filtreleme Ara Yazılımı varsayılan olarak devre dışıdır. Ara yazılımı etkinleştirmek için içinde appsettings.json/appsettings.{Environment}.jsonbir AllowedHosts anahtar tanımlayın. Değer, bağlantı noktası numaraları olmayan konak adlarının noktalı virgülle ayrılmış bir listesidir:

appsettings.json:

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

Not

İletilen Üst Bilgiler Ara Yazılımı'nın da bir AllowedHosts seçeneği vardır. İletilen Üst Bilgiler Ara Yazılımı ve Konak Filtreleme Ara Yazılımı, farklı senaryolar için benzer işlevlere sahiptir. AllowedHosts İstekler ters ara sunucu veya yük dengeleyici ile iletilirken üst bilgi korunmadığındaHost, İletilen Üst Bilgiler Ara Yazılımı ayarı uygundur. Genel kullanıma yönelik bir uç sunucu olarak kullanıldığında veya üst bilgi doğrudan iletildiğinde Host Konak Filtreleme Ara Yazılımı Kestrel ile ayar AllowedHosts uygundur.

İletilen Üst Bilgiler Ara Yazılımı hakkında daha fazla bilgi için bkz. ASP.NET Core ara sunucularla ve yük dengeleyicilerle çalışacak şekilde yapılandırma.

Libuv aktarım yapılandırması

LibuvUseLibuv () kullanımını gerektiren projeler için:

  • Uygulamanın proje dosyasına paket için Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv bir bağımlılık ekleyin:

    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                      Version="{VERSION}" />
    
  • üzerinde çağrısıUseLibuv: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 isteği boşaltma

HTTP bağlantılarını açmak zaman alır. HTTPS için de yoğun kaynak kullanır. Bu nedenle, Kestrel HTTP/1.1 protokolüne göre bağlantıları yeniden kullanma denemeleri. Bağlantının yeniden kullanılmasına izin vermek için bir istek gövdesinin tamamen kullanılması gerekir. Uygulama her zaman sunucunun yeniden yönlendirme veya 404 yanıtı döndürdüğü istekler gibi POST istek gövdesini kullanmaz. POST-redirect durumunda:

  • İstemci verilerin bir bölümünü POST zaten göndermiş olabilir.
  • Sunucu 301 yanıtını yazar.
  • Önceki istek gövdesindeki veriler tamamen okunana kadar POST bağlantı yeni bir istek için kullanılamaz.
  • Kestrel istek gövdesini boşaltmaya çalışır. İstek gövdesinin boşaltılması, verileri işlemeden okuma ve atma anlamına gelir.

Boşaltma işlemi, bağlantının yeniden kullanılmasına izin verme ile kalan verilerin boşaltılması için gereken süre arasında bir denge sağlar:

  • Boşaltma beş saniyelik zaman aşımına sahiptir ve bu zaman aşımı yapılandırılamaz.
  • veya Transfer-Encoding üst bilgisi tarafından Content-Length belirtilen tüm veriler zaman aşımından önce okunmamışsa, bağlantı kapatılır.

Bazen, yanıtı yazmadan önce veya yazdıktan sonra isteği hemen sonlandırmak isteyebilirsiniz. Örneğin, istemcilerin kısıtlayıcı veri üst sınırları olabilir, bu nedenle karşıya yüklenen verilerin sınırlanması öncelikli olabilir. Bu gibi durumlarda isteği sonlandırmak için bir denetleyiciden, Razor Sayfadan veya ara yazılımdan HttpContext.Abort'u çağırın.

çağrısı Abortyapmak için uyarılar vardır:

  • Yeni bağlantılar oluşturmak yavaş ve pahalı olabilir.
  • Bağlantı kapanmadan önce istemcinin yanıtı okuduğunun garantisi yoktur.
  • Çağrı Abort nadir olmalı ve yaygın hatalar için değil ciddi hata durumları için ayrılmalıdır.
    • Yalnızca belirli bir sorunun çözülmesi gerektiğinde arayın Abort . Örneğin, kötü amaçlı istemciler veri almaya POST çalışıyorsa veya istemci kodunda büyük veya çok sayıda isteğe neden olan bir hata olduğunda çağrısı Abort yapabilirsiniz.
    • HTTP 404 (Bulunamadı) gibi yaygın hata durumlarını çağırmayın Abort .

Çağrıdan önce HttpResponse.CompleteAsync çağrısı Abort sunucunun yanıtı yazmayı tamamlamasını sağlar. Ancak istemci davranışı tahmin edilemez ve bağlantı durdurulmadan önce yanıtı okumayabilir.

Protokol, bağlantıyı kapatmadan tek tek istek akışlarını durdurmayı desteklediğinden http/2 için bu işlem farklıdır. Beş saniyelik boşaltma zaman aşımı geçerli değildir. Yanıt tamamlandıktan sonra okunmamış istek gövdesi verileri varsa, sunucu bir HTTP/2 RST çerçevesi gönderir. Ek istek gövdesi veri çerçeveleri yoksayılır.

Mümkünse, istemcilerin Expect: 100-continue istek üst bilgisini kullanmaları ve istek gövdesini göndermeye başlamadan önce sunucunun yanıt vermesini beklemeleri daha iyidir. Bu, istemciye gereksiz verileri göndermeden önce yanıtı inceleme ve durdurma fırsatı verir.

Ek kaynaklar