Kestrel server web di ASP.NET Core

Note

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 10 dari artikel ini.

Oleh Tom Dykstra, Chris Ross, dan Stephen Halter

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel adalah server yang direkomendasikan untuk ASP.NET Core, dan dikonfigurasi secara default dalam templat proyek ASP.NET Core.

KestrelFitur-fiturnya meliputi:

  • Lintas platform:Kestrel adalah server web lintas platform yang berjalan di Windows, Linux, dan macOS.
  • Performa tinggi:Kestrel dioptimalkan untuk menangani sejumlah besar koneksi bersamaan secara efisien.
  • Ringan: Dioptimalkan untuk berjalan di lingkungan yang dibatasi sumber daya, seperti kontainer dan perangkat edge.
  • Keamanan diperkuat:Kestrel mendukung HTTPS dan diperkuat terhadap kerentanan server web.
  • Dukungan protokol yang luas:Kestrel mendukung protokol web umum, termasuk:
  • Integrasi dengan ASP.NET Core: Integrasi mulus dengan komponen ASP.NET Core lainnya, seperti alur middleware, injeksi dependensi, dan sistem konfigurasi.
  • Beban kerja fleksibel: Kestrel mendukung banyak beban kerja:
    • ASP.NET kerangka kerja aplikasi seperti API Minimal, MVC, Razor halaman, SignalR, Blazor, dan gRPC.
    • Membangun proksi terbalik dengan YARP.
  • Ekstensibilitas: Sesuaikan Kestrel melalui konfigurasi, middleware, dan transportasi kustom.
  • Diagnostik performa:Kestrel menyediakan fitur diagnostik performa bawaan, seperti pengelogan dan metrik.
  • Manajemen memori:Kestrel mencakup fitur untuk manajemen memori yang efisien. Untuk informasi selengkapnya, lihat Manajemen memori di Kestrel.

Get started

ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam Program.cs yang dihasilkan template berikut, metode WebApplication.CreateBuilder memanggil UseKestrel secara internal.

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

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

app.Run();

Untuk informasi selengkapnya tentang mengonfigurasi WebApplication dan WebApplicationBuilder, lihat Panduan cepat API minimal.

Sumber daya tambahan

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel adalah server yang direkomendasikan untuk ASP.NET Core, dan dikonfigurasi secara default dalam templat proyek ASP.NET Core.

KestrelFitur-fiturnya meliputi:

  • Lintas platform:Kestrel adalah server web lintas platform yang berjalan di Windows, Linux, dan macOS.
  • Performa tinggi:Kestrel dioptimalkan untuk menangani sejumlah besar koneksi bersamaan secara efisien.
  • Ringan: Dioptimalkan untuk berjalan di lingkungan yang dibatasi sumber daya, seperti kontainer dan perangkat edge.
  • Keamanan diperkuat:Kestrel mendukung HTTPS dan diperkuat terhadap kerentanan server web.
  • Dukungan protokol yang luas:Kestrel mendukung protokol web umum, termasuk:
  • Integrasi dengan ASP.NET Core: Integrasi mulus dengan komponen ASP.NET Core lainnya, seperti alur middleware, injeksi dependensi, dan sistem konfigurasi.
  • Beban kerja fleksibel: Kestrel mendukung banyak beban kerja:
    • ASP.NET kerangka kerja aplikasi seperti API Minimal, MVC, Razor halaman, SignalR, Blazor, dan gRPC.
    • Membangun proksi terbalik dengan YARP.
  • Ekstensibilitas: Sesuaikan Kestrel melalui konfigurasi, middleware, dan transportasi kustom.
  • Diagnostik performa:Kestrel menyediakan fitur diagnostik performa bawaan, seperti pengelogan dan metrik.

Get started

ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam Program.cs yang dihasilkan template berikut, metode WebApplication.CreateBuilder memanggil UseKestrel secara internal.

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

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

app.Run();

Untuk informasi selengkapnya tentang mengonfigurasi WebApplication dan WebApplicationBuilder, lihat Panduan cepat API minimal.

Perilaku dengan debugger terhubung

Batas waktu habis dan batas kecepatan berikut tidak diberlakukan saat debugger dilampirkan ke proses Kestrel.

Sumber daya tambahan

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel adalah server web yang disertakan dan diaktifkan secara default dalam templat proyek ASP.NET Core.

Kestrel mendukung skenario berikut:

  • HTTPS
  • HTTP/2 (kecuali di macOS†)
  • Peningkatan buram diterapkan untuk mengaktifkan WebSocket
  • Soket Unix untuk performa tinggi di belakang Nginx

†HTTP/2 akan didukung di macOS dalam rilis mendatang.

Kestrel didukung pada semua platform dan versi yang didukung .NET.

Get started

ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam Program.cs yang dihasilkan template berikut, metode WebApplication.CreateBuilder memanggil UseKestrel secara internal.

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

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

app.Run();

Untuk informasi selengkapnya tentang mengonfigurasi WebApplication dan WebApplicationBuilder, lihat Panduan cepat API minimal.

Perilaku dengan debugger terhubung

Batas waktu habis dan batas kecepatan berikut tidak diberlakukan saat debugger dilampirkan ke proses Kestrel.

Sumber daya tambahan

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel adalah server web yang disertakan dan diaktifkan secara default dalam templat proyek ASP.NET Core.

Kestrel mendukung skenario berikut:

  • HTTPS
  • HTTP/2 (kecuali di macOS†)
  • Peningkatan buram diterapkan untuk mengaktifkan WebSocket
  • Soket Unix untuk performa tinggi di belakang Nginx

†HTTP/2 akan didukung di macOS dalam rilis mendatang.

Kestrel didukung pada semua platform dan versi yang didukung .NET.

Melihat atau mengunduh kode sampel (cara mengunduh)

Get started

ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam Program.cs, metode ConfigureWebHostDefaults memanggil 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>();
        });

Untuk informasi selengkapnya tentang membangun host, lihat bagian Menyiapkan host dan Pengaturan penyusun default dari .NET Generic Host di ASP.NET Core.

Sumber daya tambahan

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel adalah server web yang disertakan secara default dalam templat proyek ASP.NET Core.

Kestrel mendukung skenario berikut:

  • HTTPS
  • Peningkatan buram diterapkan untuk mengaktifkan WebSocket
  • Soket Unix untuk performa tinggi di belakang Nginx
  • HTTP/2 (kecuali di macOS†)

†HTTP/2 akan didukung di macOS dalam rilis mendatang.

Kestrel didukung pada semua platform dan versi yang didukung .NET.

Melihat atau mengunduh kode sampel (cara mengunduh)

Dukungan HTTP/2

HTTP/2 tersedia untuk aplikasi ASP.NET Core jika persyaratan dasar berikut terpenuhi:

  • Sistem operasi†
    • Server Windows 2016/Windows 10 atau yang lebih baru‡
    • Linux dengan OpenSSL 1.0.2 atau yang lebih baru (misalnya, Ubuntu 16.04 atau yang lebih baru)
  • Kerangka kerja target: .NET Core 2.2 atau yang lebih baru
  • Koneksi Negosiasi Protokol Lapisan Aplikasi (ALPN)
  • TLS 1.2 atau koneksi yang lebih baru

†HTTP/2 akan didukung di macOS dalam rilis mendatang. Kestrel‡ memiliki dukungan terbatas untuk HTTP/2 di Windows Server 2012 R2 dan Windows 8.1. Dukungan terbatas karena daftar rangkaian cipher TLS yang didukung yang tersedia pada sistem operasi ini terbatas. Sertifikat yang dihasilkan menggunakan Elliptic Curve Digital Signature Algorithm (ECDSA) mungkin diperlukan untuk mengamankan koneksi TLS.

Jika koneksi HTTP/2 dibuat, HttpRequest.Protocol laporkan HTTP/2.

Dimulai dengan .NET Core 3.0, HTTP/2 diaktifkan secara default. Untuk informasi selengkapnya tentang konfigurasi, lihat Kestrel bagian opsi dan ListenOptions.Protocols .

Kapan menggunakan Kestrel dengan proksi terbalik

Kestrel dapat digunakan sendiri atau dengan server proksi terbalik. Server proksi terbalik menerima permintaan HTTP dari jaringan dan meneruskannya ke Kestrel. Contoh server proksi terbalik meliputi:

Kestrel digunakan sebagai server web tepi (menghadap Internet):

Kestrel berkomunikasi langsung dengan Internet tanpa server proksi terbalik

Kestrel digunakan dalam konfigurasi proksi terbalik:

Kestrel berkomunikasi secara tidak langsung dengan Internet melalui server proksi terbalik, seperti IIS, Nginx, atau Apache

Konfigurasi mana pun, baik dengan atau tanpa server proksi terbalik, adalah konfigurasi hosting yang didukung.

Kestrel yang digunakan sebagai server edge tanpa server proksi terbalik tidak mendukung penggunaan IP dan port yang sama di antara beberapa proses. Ketika Kestrel dikonfigurasi untuk mendengarkan pada port, Kestrel menangani semua lalu lintas pada port tersebut terlepas dari header permintaan Host. Proksi terbalik yang dapat berbagi port memiliki kemampuan untuk meneruskan permintaan ke Kestrel pada IP dan port unik.

Bahkan jika server proksi terbalik tidak diperlukan, menggunakan server proksi terbalik mungkin merupakan pilihan yang baik.

Sebuah proksi terbalik

  • Dapat membatasi area permukaan publik yang terekspos dari aplikasi yang dihostingnya.
  • Berikan lapisan konfigurasi tambahan dan keamanan cyber yang mendalam.
  • Mungkin terintegrasi lebih baik dengan infrastruktur yang ada.
  • Menyederhanakan penyeimbangan beban dan konfigurasi komunikasi aman (HTTPS). Hanya server proksi terbalik yang memerlukan sertifikat X.509, dan server tersebut dapat berkomunikasi dengan server aplikasi di jaringan internal menggunakan HTTP biasa.

Warning

Penghostingan dalam konfigurasi proksi terbalik memerlukan konfigurasi middleware header yang diteruskan.

Kestrel di aplikasi ASP.NET Core

ASP.NET templat proyek Core digunakan Kestrel secara default. Dalam Program.cs, metode ConfigureWebHostDefaults memanggil 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>();
        });

Untuk informasi selengkapnya tentang membangun host, lihat bagian Menyiapkan host dan Pengaturan penyusun default dari .NET Generic Host di ASP.NET Core.

Untuk menyediakan konfigurasi tambahan setelah memanggil ConfigureWebHostDefaults, gunakan ConfigureKestrel:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Opsi Kestrel

Server Kestrel web memiliki opsi konfigurasi batasan yang sangat berguna dalam penyebaran yang terhubung ke Internet.

Tentukan batasan pada properti Limits dari kelas KestrelServerOptions. Properti Limits menyimpan instans KestrelServerLimits kelas.

Contoh berikut menggunakan namespace Microsoft.AspNetCore.Server.Kestrel.Core

using Microsoft.AspNetCore.Server.Kestrel.Core;

Dalam contoh yang ditunjukkan nanti dalam artikel ini, Kestrel opsi dikonfigurasi dalam kode C#. Kestrel opsi juga dapat diatur menggunakan penyedia konfigurasi. Misalnya, Penyedia Konfigurasi Berkas dapat memuat Kestrel konfigurasi dari appsettings.json atau appsettings.{Environment}.json file.

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

Note

KestrelServerOptions dan konfigurasi titik akhir dapat diatur dari penyedia konfigurasi. Konfigurasi yang tersisa Kestrel harus dikonfigurasi dalam kode C#.

Gunakan salah satu pendekatan berikut:

  • Konfigurasikan Kestrel di Startup.ConfigureServices:

    1. Masukkan instans IConfiguration ke Startup dalam kelas . Contoh berikut mengasumsikan bahwa konfigurasi yang disuntikkan ditetapkan ke properti Configuration.

    2. Di Startup.ConfigureServices, masukkan bagian Kestrel konfigurasi ke dalam konfigurasi Kestrel.

      using Microsoft.Extensions.Configuration

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<KestrelServerOptions>(
            Configuration.GetSection("Kestrel"));
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        ...
    }
}

  • Konfigurasikan Kestrel saat membangun host:

    Di Program.cs, masukkan bagian Kestrel konfigurasi ke dalam konfigurasi Kestrel.

    // using Microsoft.Extensions.DependencyInjection;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.Configure<KestrelServerOptions>(
                context.Configuration.GetSection("Kestrel"));
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Kedua pendekatan sebelumnya berfungsi dengan penyedia konfigurasi apa pun.

Batas waktu tetap hidup

KeepAliveTimeout

Mendapatkan atau mengatur keep-alive timeout. Disetel ke 2 menit.

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

Jumlah koneksi klien maksimal

MaxConcurrentConnections MaxConcurrentUpgradedConnections

Jumlah maksimum koneksi TCP terbuka bersamaan dapat diatur untuk seluruh aplikasi dengan kode berikut:

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

Ada batas terpisah untuk koneksi yang telah ditingkatkan dari HTTP atau HTTPS ke protokol lain (misalnya, pada permintaan WebSockets). Setelah koneksi ditingkatkan, koneksi tidak dihitung terhadap MaxConcurrentConnections batas.

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

Jumlah maksimum koneksi tidak terbatas (null) secara default.

Ukuran badan permintaan maksimum

MaxRequestBodySize

Ukuran isi permintaan maksimum default adalah 30.000.000 byte, yaitu sekitar 28,6 MB.

Pendekatan yang disarankan untuk mengambil alih batas dalam aplikasi ASP.NET Core MVC adalah dengan menggunakan RequestSizeLimitAttribute atribut pada metode tindakan:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

Berikut adalah contoh yang menunjukkan cara mengonfigurasi batasan untuk aplikasi pada setiap permintaan:

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

Ambil alih pengaturan pada permintaan tertentu di middleware:

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

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

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

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

Pengecualian dilemparkan jika aplikasi mengonfigurasi batas pada permintaan setelah aplikasi mulai membaca permintaan. Terdapat properti IsReadOnly yang menunjukkan jika properti MaxRequestBodySize dalam mode baca-saja, yang artinya sudah terlambat untuk mengonfigurasi batas.

Saat sebuah aplikasi dijalankan di luar proses di belakang "Modul ASP.NET Core", batas ukuran isi permintaan dinonaktifkan karena IIS sudah menetapkan batas.

Tingkat data isi permintaan minimum

MinRequestBodyDataRate MinResponseDataRate

Kestrel memeriksa setiap detik jika data tiba pada tingkat yang ditentukan dalam byte/detik. Jika tingkat turun di bawah minimum, koneksi akan kehabisan waktu. Masa tenggang adalah jumlah waktu yang Kestrel memberi klien untuk meningkatkan tingkat pengirimannya hingga minimum; tarif tidak diperiksa selama waktu tersebut. Masa tenggang membantu menghindari putusnya koneksi yang awalnya mengirim data pada laju lambat yang disebabkan oleh proses slow-start TCP.

Tingkat minimum default adalah 240 byte/detik dengan masa tenggang 5 detik.

Tarif minimum juga berlaku untuk respons. Kode untuk mengatur batas permintaan dan batas respons sama kecuali untuk memiliki RequestBody atau Response dalam nama properti dan antarmuka.

Berikut adalah contoh yang menunjukkan cara mengonfigurasi tarif data minimum di 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);
})

Ambil alih batas tarif minimum per permintaan di middleware:

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

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

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

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

Referensi IHttpMinResponseDataRateFeature yang ada dalam sampel sebelumnya tidak ada dalam HttpContext.Features untuk permintaan HTTP/2 karena mengubah batas laju secara per permintaan umumnya tidak didukung oleh HTTP/2 dikarenakan dukungan protokol tersebut untuk multipleksing permintaan. Namun, IHttpMinRequestBodyDataRateFeature masih ada HttpContext.Features untuk permintaan HTTP/2, karena batas kecepatan pembacaan masih dapat sepenuhnya dinonaktifkan pada setiap permintaan dengan mengatur ke IHttpMinRequestBodyDataRateFeature.MinDataRate bahkan untuk permintaan HTTP/2. Mencoba membaca IHttpMinRequestBodyDataRateFeature.MinDataRate atau mencoba mengaturnya ke nilai selain null akan mengakibatkan NotSupportedException dilemparkan dengan permintaan HTTP/2.

Batas laju di seluruh server yang dikonfigurasi melalui KestrelServerOptions.Limits masih berlaku untuk koneksi HTTP/1.x dan HTTP/2.

Batas waktu untuk header permintaan

RequestHeadersTimeout

Mendapatkan atau mengatur jumlah maksimum waktu yang dihabiskan server untuk menerima header permintaan. Secara default diatur ke 30 detik.

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

Aliran maksimum per koneksi

Http2.MaxStreamsPerConnection membatasi jumlah aliran permintaan bersamaan per koneksi HTTP/2. Aliran berlebih ditolak.

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

Nilai default adalah 100.

Ukuran header tabel

Dekoder HPACK mendekompresi header HTTP untuk koneksi HTTP/2. Http2.HeaderTableSize membatasi ukuran tabel kompresi header yang digunakan dekoder HPACK. Nilai disediakan dalam oktet dan harus lebih besar dari nol (0).

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

Nilai defaultnya adalah 4096.

Ukuran bingkai maksimum

Http2.MaxFrameSize menunjukkan ukuran maksimum yang diizinkan dari payload bingkai koneksi HTTP/2 yang diterima atau dikirim oleh server. Nilai disediakan dalam oktet dan harus antara 2^14 (16.384) dan 2^24-1 (16.777.215).

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

Nilai defaultnya adalah 2^14 (16.384).

Ukuran header permintaan maksimum

Http2.MaxRequestHeaderFieldSize menunjukkan ukuran maksimum yang diizinkan dalam oktet nilai header permintaan. Batas ini berlaku untuk nama dan nilai dalam representasi terkompresi dan tidak dikompresi. Nilai harus lebih besar dari nol (0).

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

Nilai defaultnya adalah 8.192.

Ukuran jendela koneksi awal

Http2.InitialConnectionWindowSize menunjukkan jumlah maksimum data isi permintaan dalam byte yang dapat di-buffer oleh server pada satu waktu, yang digabungkan di seluruh permintaan (stream) per koneksi. Permintaan juga dibatasi oleh Http2.InitialStreamWindowSize. Nilai harus lebih besar dari atau sama dengan 65.535 dan kurang dari 2^31 (2.147.483.648).

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

Nilai defaultnya adalah 128 KB (131.072).

Ukuran jendela aliran awal

Http2.InitialStreamWindowSize menunjukkan data isi permintaan maksimum dalam byte yang di-buffer server untuk setiap permintaan (stream). Permintaan juga dibatasi oleh Http2.InitialConnectionWindowSize. Nilai harus lebih besar dari atau sama dengan 65.535 dan kurang dari 2^31 (2.147.483.648).

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

Nilai defaultnya adalah 96 KB (98.304).

Trailers

Http Trailer mirip dengan Header HTTP, kecuali dikirim setelah isi respons dikirim. Untuk IIS dan HTTP.sys, hanya trailer respons HTTP/2 yang didukung.

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

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

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

Dalam kode contoh sebelumnya:

  • SupportsTrailers memastikan bahwa trailer didukung untuk respons.
  • DeclareTrailer menambahkan nama trailer yang ditentukan ke header respons Trailer. Mendeklarasikan trailer respons bersifat opsional, tetapi disarankan. Jika DeclareTrailer dipanggil, itu harus dilakukan sebelum header respons dikirim.
  • AppendTrailer menambahkan trailer.

Reset

Reset memungkinkan server untuk mengatur ulang permintaan HTTP/2 dengan kode kesalahan tertentu. Permintaan reset dianggap dibatalkan.

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

Reset dalam contoh kode sebelumnya menentukan INTERNAL_ERROR kode kesalahan. Untuk informasi selengkapnya tentang kode kesalahan HTTP/2, kunjungi bagian kode kesalahan spesifikasi HTTP/2.

Masukan/Keluaran Sinkron

AllowSynchronousIO mengontrol apakah I/O sinkron diizinkan untuk permintaan dan respons. Nilai defaultnya adalah false.

Warning

Sejumlah besar operasi I/O sinkron yang terblokir dapat menyebabkan kekurangan sumber daya pada kumpulan utas, yang membuat aplikasi tidak responsif. Hanya aktifkan AllowSynchronousIO saat menggunakan pustaka yang tidak mendukung I/O asinkron.

Contoh berikut mengaktifkan I/O sinkron:

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

Untuk informasi tentang opsi dan batasan lainnya Kestrel , lihat:

Konfigurasi titik akhir

Secara default, ASP.NET Core mengikat ke:

  • http://localhost:5000
  • https://localhost:5001 (saat sertifikat pengembangan lokal ada)

Tentukan URL menggunakan:

  • ASPNETCORE_URLS variabel lingkungan.
  • --urls argumen baris perintah.
  • urls kunci konfigurasi host.
  • UseUrls metode ekstensi.

Nilai yang disediakan menggunakan pendekatan ini dapat berupa satu atau beberapa titik akhir HTTP dan HTTPS (HTTPS jika sertifikasi default tersedia). Konfigurasikan nilai sebagai daftar yang dipisahkan titik koma (misalnya, "Urls": "http://localhost:8000;http://localhost:8001").

Untuk informasi selengkapnya tentang pendekatan ini, lihat URL Server dan Penggantian Konfigurasi.

Sertifikat pengembangan dibuat:

Beberapa browser memerlukan pemberian izin eksplisit untuk mempercayai sertifikat pengembangan lokal.

Templat proyek mengonfigurasi aplikasi untuk berjalan di HTTPS secara default dan menyertakan dukungan pengalihan HTTPS dan HSTS.

Panggil metode Listen atau ListenUnixSocket pada KestrelServerOptions untuk mengonfigurasi awalan URL dan port untuk Kestrel.

UseUrls --urls, argumen baris perintah, urls kunci konfigurasi host, dan ASPNETCORE_URLS variabel lingkungan juga berfungsi tetapi memiliki batasan yang dicatat nanti di bagian ini (sertifikat default harus tersedia untuk konfigurasi titik akhir HTTPS).

KestrelServerOptions Konfigurasi:

ConfigureEndpointDefaults(Action<ListenOptions>) (MengonfigurasiPengaturanDefaultEndpoint(Aksi<PilihanDengar>))

Menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir yang ditentukan. Memanggil ConfigureEndpointDefaults beberapa kali menggantikan Action sebelumnya dengan Action yang terakhir ditentukan.

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

Note

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.

`MengonfigurasiHttpsDefaults(Action<HttpsConnectionAdapterOptions>)`

Menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir HTTPS. Memanggil ConfigureHttpsDefaults beberapa kali menggantikan Action sebelumnya dengan Action yang terakhir ditentukan.

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

Note

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.

Configure(IConfiguration)

Membuat pemuat konfigurasi untuk menyiapkan Kestrel yang mengambil IConfiguration sebagai input. Konfigurasi harus dilingkup ke bagian konfigurasi untuk Kestrel.

ListenOptions.UseHttps

Konfigurasikan Kestrel untuk menggunakan HTTPS.

ListenOptions.UseHttps Ekstensi:

  • UseHttps: Konfigurasikan Kestrel untuk menggunakan HTTPS dengan sertifikat default. Melemparkan pengecualian jika tidak ada sertifikat default yang dikonfigurasi.
  • 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 Parameter-parameternya:

  • filename adalah jalur dan nama file file sertifikat, relatif terhadap direktori yang berisi file konten aplikasi.
  • password adalah kata sandi yang diperlukan untuk mengakses data sertifikat X.509.
  • configureOptions Action adalah untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
  • storeName adalah penyimpanan sertifikat tempat sertifikat dimuat.
  • subject adalah nama subjek untuk sertifikat.
  • allowInvalid menunjukkan apakah sertifikat yang tidak valid harus dipertimbangkan, seperti sertifikat yang ditandatangani sendiri.
  • location adalah lokasi penyimpanan untuk memuat sertifikat.
  • serverCertificate adalah sertifikat X.509.

Dalam produksi, HTTPS harus dikonfigurasi secara eksplisit. Minimal, sertifikat default harus disediakan.

Konfigurasi yang didukung dijelaskan berikutnya:

  • Tidak ada konfigurasi
  • Ganti sertifikat default dari konfigurasi
  • Mengubah default dalam kode

Tidak ada konfigurasi

Kestrel aktif pada http://localhost:5000 dan https://localhost:5001 (jika sertifikat default tersedia).

Ganti sertifikat default dari konfigurasi

CreateDefaultBuilder memanggil Configure(context.Configuration.GetSection("Kestrel")) secara default untuk memuat konfigurasi Kestrel. Skema konfigurasi pengaturan aplikasi HTTPS default tersedia untuk Kestrel. Konfigurasikan beberapa titik akhir, termasuk URL dan sertifikat yang akan digunakan, baik dari file di disk atau dari penyimpanan sertifikat.

Dalam contoh berikut appsettings.json :

  • Atur AllowInvalid ke true untuk mengizinkan penggunaan sertifikat yang tidak valid (misalnya, sertifikat yang ditandatangani sendiri).
  • Setiap titik akhir HTTPS yang tidak menentukan sertifikat (HttpsDefaultCert dalam contoh berikut) kembali ke sertifikat yang ditentukan di bawah Sertifikat>Default atau sertifikat pengembangan.
{
  "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>"
      }
    }
  }
}

Alternatif untuk menggunakan Jalur dan Kata Sandi untuk simpul sertifikat apa pun adalah menentukan sertifikat menggunakan bidang penyimpanan sertifikat. Misalnya, sertifikat Certificates>Default dapat ditentukan sebagai:

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

Catatan skema:

  • Nama titik akhir tidak peka huruf besar/kecil. Misalnya, HTTPS dan Https valid.
  • Parameter Url diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkat Urls atas kecuali bahwa parameter tersebut terbatas pada satu nilai.
  • Titik akhir ini menggantikan yang ditentukan dalam konfigurasi tingkat Urls atas daripada menambahkannya. Titik akhir yang ditentukan dalam kode melalui Listen bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi.
  • Bagian Certificate ini bersifat opsional. Jika bagian Certificate tidak ditentukan, default yang ditentukan dalam skenario sebelumnya akan digunakan. Jika tidak ada default yang tersedia, server akan melempar pengecualian dan gagal memulai.
  • Bagian ini Certificate mendukung sertifikat Path–Password dan Subject–Store .
  • Sejumlah titik akhir dapat didefinisikan dengan cara ini selama tidak menyebabkan konflik port.
  • options.Configure(context.Configuration.GetSection("{SECTION}")) mengembalikan KestrelConfigurationLoader dengan metode .Endpoint(string name, listenOptions => { }) yang dapat digunakan untuk melengkapi pengaturan endpoint (titik akhir) yang dikonfigurasi.
webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader dapat langsung diakses untuk terus melakukan iterasi pada loader yang ada, seperti yang disediakan oleh CreateDefaultBuilder.

  • Bagian konfigurasi untuk setiap titik akhir tersedia pada opsi dalam Endpoint metode sehingga pengaturan kustom dapat dibaca.
  • Beberapa konfigurasi dapat dimuat dengan memanggil kembali options.Configure(context.Configuration.GetSection("{SECTION}")) dengan bagian lain. Hanya konfigurasi terakhir yang digunakan, kecuali Load secara eksplisit dipanggil pada instans sebelumnya. Metapackage tidak memanggil Load sehingga bagian konfigurasi defaultnya dapat diganti.
  • KestrelConfigurationLoader mencerminkan Listen keluarga API dari KestrelServerOptions sebagai Endpoint kelebihan beban, sehingga titik akhir kode dan konfigurasi dapat dikonfigurasi di tempat yang sama. Kelebihan beban ini tidak menggunakan nama dan hanya menggunakan pengaturan default dari konfigurasi.

Mengubah default dalam kode

ConfigureEndpointDefaults dan ConfigureHttpsDefaults dapat digunakan untuk mengubah pengaturan default untuk ListenOptions dan HttpsConnectionAdapterOptions, termasuk mengganti sertifikat default yang ditentukan dalam skenario sebelumnya. ConfigureEndpointDefaults dan ConfigureHttpsDefaults harus dipanggil sebelum titik akhir dikonfigurasi.

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

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

Kestrel dukungan untuk SNI

Indikasi Nama Server (SNI) dapat digunakan untuk menghosting beberapa domain pada alamat IP dan port yang sama. Agar SNI berfungsi, klien mengirim nama host untuk sesi aman ke server selama jabat tangan TLS sehingga server dapat memberikan sertifikat yang benar. Klien menggunakan sertifikat yang dilengkapi untuk komunikasi terenkripsi dengan server selama sesi aman yang mengikuti jabat tangan TLS.

Kestrel mendukung SNI melalui ServerCertificateSelector panggilan balik. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat yang sesuai.

Dukungan SNI memerlukan:

  • Beroperasi pada kerangka kerja target netcoreapp2.1 atau yang lebih baru. Pada net461 atau lebih baru, panggilan balik dipanggil tetapi name selalu null. name juga null jika klien tidak memberikan parameter nama host dalam jabat tangan TLS.
  • Semua situs web berjalan pada instans yang sama Kestrel . Kestrel tidak mendukung berbagi alamat IP dan port di beberapa instans tanpa proksi terbalik.
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;
            };
        });
    });
});

Pengelogan koneksi

Panggil UseConnectionLogging untuk mengeluarkan log level Debug untuk komunikasi tingkat byte pada koneksi. Pengelogan koneksi sangat membantu untuk memecahkan masalah dalam komunikasi tingkat rendah, seperti selama enkripsi TLS dan di belakang proksi. Jika UseConnectionLogging ditempatkan sebelum UseHttps, lalu lintas terenkripsi dicatat. Jika UseConnectionLogging ditempatkan setelah UseHttps, lalu lintas yang didekripsi dicatat.

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

Ikat ke soket TCP

Metode ini Listen mengikat ke soket TCP, dan opsi lambda mengizinkan konfigurasi sertifikat X.509:

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

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

Contoh mengonfigurasi HTTPS untuk endpoint dengan ListenOptions. Gunakan API yang sama untuk mengonfigurasi pengaturan lain Kestrel untuk titik akhir tertentu.

Pada Windows, sertifikat yang ditandatangani sendiri dapat dibuat dengan menggunakan cmdlet PowerShell New-SelfSignedCertificate. Untuk contoh yang tidak didukung, lihat file sertifikat UpdateIISExpressSSLForChrome.ps1 pada GitHub.

Di macOS, Linux, dan Windows, buat sertifikat dapat dibuat dengan menggunakan OpenSSL.

Mengikat ke soket Unix

Dengarkan soket Unix dengan ListenUnixSocket untuk meningkatkan performa dengan Nginx, seperti yang ditunjukkan dalam contoh ini:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • Dalam file konfigurasi Nginx, atur entri ke server>location>proxy_passhttp://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} adalah nama soket yang disediakan untuk ListenUnixSocket (misalnya, kestrel-test.sock dalam contoh sebelumnya).
  • Pastikan bahwa soket dapat ditulis oleh Nginx (misalnya, chmod go+w /tmp/kestrel-test.sock).

Port 0

Ketika nomor 0 port ditentukan, Kestrel secara dinamis mengikat port yang tersedia. Contoh berikut menunjukkan cara menentukan port Kestrel mana yang sebenarnya terikat pada runtime:

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

Saat aplikasi dijalankan, output jendela konsol menunjukkan port dinamis tempat aplikasi dapat dicapai:

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

Limitations

Konfigurasikan titik akhir dengan pendekatan berikut:

  • UseUrls
  • --urls argumen baris perintah
  • urls kunci konfigurasi host
  • ASPNETCORE_URLS Variabel lingkungan

Metode ini berguna untuk membuat kode berfungsi dengan server selain Kestrel. Namun, perhatikan batasan berikut:

  • HTTPS tidak dapat digunakan dengan pendekatan ini kecuali sertifikat default disediakan dalam konfigurasi titik akhir HTTPS (misalnya, menggunakan KestrelServerOptions konfigurasi atau file konfigurasi seperti yang ditunjukkan sebelumnya dalam topik ini).
  • Ketika pendekatan Listen dan UseUrls digunakan secara bersamaan, titik akhir Listen menggantikan titik akhir UseUrls.

Konfigurasi titik akhir IIS

Saat menggunakan IIS, pengikatan URL untuk pengikatan penimpaan IIS diatur oleh atau ListenUseUrls. Untuk informasi selengkapnya, lihat topik Modul Inti ASP.NET.

ListenOptions.Protocols

Properti Protocols menetapkan protokol HTTP (HttpProtocols) yang diaktifkan pada titik akhir koneksi atau untuk server. Tetapkan properti Protocols ke nilai dari enum HttpProtocols.

HttpProtocols nilai enum Protokol koneksi diizinkan
Http1 HTTP/1.1 saja. Dapat digunakan dengan atau tanpa TLS.
Http2 Hanya HTTP/2. Dapat digunakan tanpa TLS hanya jika klien mendukung mode Pengetahuan Awal.
Http1AndHttp2 HTTP/1.1 dan HTTP/2. HTTP/2 mengharuskan klien untuk memilih HTTP/2 dalam jabat tangan Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS. Jika tidak, koneksi akan default ke HTTP/1.1.

Nilai default ListenOptions.Protocols untuk titik akhir apa pun adalah HttpProtocols.Http1AndHttp2.

Pembatasan TLS untuk HTTP/2:

  • TLS versi 1.2 atau yang lebih baru
  • Negosiasi ulang dinonaktifkan
  • Pemadatan dinonaktifkan
  • Ukuran minimum untuk pertukaran kunci ephemeral:
    • Kurva eliptik Diffie-Hellman (ECDHE) [RFC4492]: 224 bit minimum
    • Bidang terbatas Diffie-Hellman (DHE) [TLS12]: minimum 2048 bit
  • Cipher suite tidak dilarang.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] dengan kurva elips P-256 [FIPS186] didukung secara default.

Contoh berikut mengizinkan koneksi HTTP/1.1 dan HTTP/2 pada port 8000. Koneksi diamankan oleh TLS dengan sertifikat yang disediakan:

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

Gunakan middleware koneksi untuk menyaring handshake TLS berdasarkan masing-masing koneksi untuk cipher tertentu jika diperlukan.

Contoh berikut melemparkan NotSupportedException untuk algoritma sandi apa pun yang tidak didukung aplikasi. Atau, tentukan dan bandingkan ITlsHandshakeFeature.CipherAlgorithm dengan daftar suite sandi yang dapat diterima.

Tidak ada enkripsi yang digunakan pada algoritma cipher CipherAlgorithmType.Null.

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

Pemfilteran koneksi juga dapat dikonfigurasi melalui 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();
        });
    });
});

Di Linux, CipherSuitesPolicy dapat digunakan untuk memfilter jabat tangan TLS berdasarkan per koneksi:

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

Mengatur protokol dari konfigurasi

CreateDefaultBuilder memanggil serverOptions.Configure(context.Configuration.GetSection("Kestrel")) secara default untuk memuat konfigurasi Kestrel.

Contoh berikut appsettings.json menetapkan HTTP/1.1 sebagai protokol koneksi default untuk semua titik akhir:

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

Contoh berikut appsettings.json menetapkan protokol koneksi HTTP/1.1 untuk titik akhir tertentu:

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

Protokol yang ditentukan dalam kode mengesampingkan nilai yang ditetapkan oleh konfigurasi.

Awalan URL

Saat menggunakan UseUrlsargumen baris perintah, --urlsurls kunci konfigurasi host, atau ASPNETCORE_URLS variabel lingkungan, awalan URL dapat berada dalam salah satu format berikut.

Hanya awalan URL HTTP yang valid. Kestrel tidak mendukung HTTPS saat mengonfigurasi pengikatan URL menggunakan UseUrls.

  • Alamat IPv4 dengan nomor port

    http://65.55.39.10:80/

    0.0.0.0 adalah kasus khusus yang mengikat semua alamat IPv4.

  • Alamat IPv6 dengan nomor port

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

    [::] adalah IPv6 setara dengan IPv4 0.0.0.0.

  • Nama host dengan nomor port

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

    Nama host, *, dan +, tidak istimewa. Apa pun yang tidak dikenali sebagai alamat IP yang valid atau localhost akan terhubung ke semua IP IPv4 dan IPv6. Untuk mengikat nama host yang berbeda ke aplikasi ASP.NET Core yang berbeda pada port yang sama, gunakan HTTP.sys atau server proksi terbalik, seperti IIS, Nginx, atau Apache.

    Warning

    Hosting dalam konfigurasi proksi terbalik memerlukan konfigurasi middleware header yang diteruskan.

  • Nama host localhost dengan nomor port atau alamat IP loopback dengan nomor port.

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

    Ketika localhost ditentukan, Kestrel berupaya mengikat ke antarmuka loopback IPv4 dan IPv6. Jika port yang diminta sedang digunakan oleh layanan lain pada antarmuka loopback, Kestrel gagal memulai. Jika antarmuka loopback tidak tersedia karena alasan lain (paling umum karena IPv6 tidak didukung), Kestrel catat peringatan.

Pemfilteran host

Meskipun Kestrel mendukung konfigurasi berdasarkan awalan seperti http://example.com:5000, Kestrel sebagian besar mengabaikan nama host. Host localhost adalah kasus khusus yang digunakan untuk mengikat ke alamat loopback. Host apa pun selain alamat IP eksplisit mengikat semua alamat IP publik. Host header tidak divalidasi.

Sebagai solusinya, gunakan middleware pemfilteran host. Middleware pemfilteran host disediakan oleh Microsoft. Paket AspNetCore.HostFiltering, yang secara implisit disediakan untuk aplikasi ASP.NET Core. Middleware ditambahkan oleh CreateDefaultBuilder, yang memanggil AddHostFiltering:

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

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

Middleware pemfilteran host dinonaktifkan secara default. Untuk mengaktifkan middleware, tentukan AllowedHosts kunci diappsettings.json/appsettings.{Environment}.json . Nilainya adalah daftar nama host yang dibatasi titik koma tanpa nomor port:

appsettings.json:

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

Note

Middleware untuk header yang diteruskan juga memiliki opsi AllowedHosts. Middleware header yang diteruskan dan middleware pemfilteran host memiliki fungsionalitas serupa untuk skenario yang berbeda. Menyetel AllowedHosts dengan middleware header yang diteruskan tepat jika header Host tidak dipertahankan saat meneruskan permintaan melalui server proksi terbalik atau penyeimbang beban. Pengaturan AllowedHosts dengan middleware pemfilteran host sudah tepat ketika Kestrel digunakan sebagai server tepi publik atau ketika header Host diteruskan secara langsung.

Untuk informasi selengkapnya tentang middleware header yang diteruskan, lihat Mengonfigurasi ASP.NET Core agar berfungsi dengan server proksi dan penyeimbang beban.

Konfigurasi transportasi Libuv

Untuk proyek yang memerlukan penggunaan Libuv (UseLibuv):

  • Tambahkan dependensi untuk Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv paket ke file proyek aplikasi:

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

  • Hubungi UseLibuv di 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>();
            });
}

Pengurasan permintaan HTTP/1.1

Membuka koneksi HTTP memakan waktu. Untuk HTTPS, ini juga membutuhkan banyak sumber daya. Oleh karena itu, Kestrel coba gunakan kembali koneksi sesuai protokol HTTP/1.1. Isi permintaan harus sepenuhnya diproses untuk memungkinkan koneksi digunakan kembali. Aplikasi ini tidak selalu memproses isi permintaan, seperti pada permintaan POST di mana server mengembalikan respons pengalihan atau 404. Dalam kasus POST-redirect:

  • Klien mungkin sudah mengirim bagian dari POST data.
  • Server menulis respons 301.
  • Koneksi tidak dapat digunakan untuk permintaan baru sampai POST data dari isi permintaan sebelumnya telah dibaca sepenuhnya.
  • Kestrel mencoba untuk menguras isi permintaan. Menguras isi permintaan berarti membaca dan membuang data tanpa memprosesnya.

Proses pengosongan membuat kompromi antara memungkinkan koneksi digunakan kembali dan waktu yang diperlukan untuk mengosongkan sisa data.

  • Pengurasan memiliki batas waktu lima detik, yang tidak dapat dikonfigurasi.
  • Jika semua data yang ditentukan oleh Content-Length header atau Transfer-Encoding belum dibaca sebelum batas waktu, koneksi ditutup.

Terkadang Anda mungkin ingin segera mengakhiri permintaan, sebelum atau sesudah menulis respons. Misalnya, klien mungkin memiliki batas data yang ketat, sehingga membatasi data yang diunggah mungkin menjadi prioritas. Dalam kasus seperti itu untuk mengakhiri permintaan, panggil HttpContext.Abort dari pengontrol, Razor Halaman, atau middleware.

Ada peringatan untuk memanggil Abort:

  • Membuat koneksi baru bisa lambat dan mahal.
  • Tidak ada jaminan bahwa klien telah membaca respons sebelum koneksi ditutup.
  • Panggilan Abort harus jarang terjadi dan dicadangkan untuk kasus kesalahan yang parah, bukan kesalahan umum.
    • Hanya panggil Abort ketika masalah tertentu perlu diselesaikan. Misalnya, panggil Abort jika klien berbahaya mencoba data POST atau ketika ada bug dalam kode klien yang menyebabkan permintaan besar atau banyak.
    • Jangan panggil Abort untuk situasi kesalahan umum, seperti HTTP 404 (Tidak Ditemukan).

Memanggil HttpResponse.CompleteAsync sebelum memanggil Abort memastikan bahwa server telah selesai menulis respons. Namun, perilaku klien tidak dapat diprediksi dan mereka mungkin tidak membaca respons sebelum koneksi dibatalkan.

Proses ini berbeda untuk HTTP/2 karena protokol mendukung pembatalan aliran permintaan individual tanpa menutup koneksi. Batas waktu pengurasan lima detik tidak berlaku. Jika ada data isi permintaan yang belum dibaca setelah menyelesaikan respons, maka server mengirim bingkai HTTP/2 RST. Kerangka data isi permintaan tambahan diabaikan.

Jika memungkinkan, lebih baik bagi klien untuk menggunakan header permintaan Expect: 100-continue dan menunggu server merespons sebelum mulai mengirim isi permintaan. Itu memberi klien kesempatan untuk memeriksa respons dan membatalkan sebelum mengirim data yang tidak diperlukan.

Sumber daya tambahan

  • Last updated on