Kestrel server web di ASP.NET Core
Catatan
Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Peringatan
Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Penting
Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.
Untuk rilis saat ini, lihat versi .NET 8 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.
Memulai
ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam template-generated Program.cs
berikut , WebApplication.CreateBuilder metode 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 Referensi cepat API minimal.
Sertifikat klien opsional
Untuk informasi tentang aplikasi yang harus melindungi subset aplikasi dengan sertifikat, lihat Sertifikat klien opsional.
Perilaku dengan debugger terlampir
Batas waktu habis dan tarif berikut tidak diberlakukan saat debugger dilampirkan ke Kestrel proses:
- KestrelServerLimits.KeepAliveTimeout
- KestrelServerLimits.RequestHeadersTimeout
- KestrelServerLimits.MinRequestBodyDataRate
- KestrelServerLimits.MinResponseDataRate
- IConnectionTimeoutFeature
- IHttpMinRequestBodyDataRateFeature
- IHttpMinResponseDataRateFeature
Sumber Daya Tambahan:
- Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel
- Sumber untuk
WebApplication.CreateBuilder
panggilan metode keUseKestrel
- Mengonfigurasi opsi untuk server web ASP.NET Core Kestrel
- Menggunakan HTTP/2 dengan server web ASP.NET Core Kestrel
- Kapan menggunakan proksi terbalik dengan server web ASP.NET Core Kestrel
- Pemfilteran host dengan server web ASP.NET Core Kestrel
- Memecahkan masalah dan mendebug proyek ASP.NET Core
- Menerapkan HTTPS di ASP.NET Core
- Konfigurasikan ASP.NET Core agar berfungsi dengan server proksi dan penyeimbang beban
- RFC 9110: Semantik HTTP (Bagian 7.2: Host dan :otoritas)
- Saat menggunakan soket UNIX di Linux, soket tidak secara otomatis dihapus pada penonaktifan aplikasi. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Catatan
Pada ASP.NET Core 5.0, Kestreltransportasi libuv sudah usang. Transportasi libuv tidak menerima pembaruan untuk mendukung platform OS baru, seperti Windows ARM64, dan akan dihapus dalam rilis mendatang. Hapus panggilan apa pun ke metode usang UseLibuv dan gunakan Kestreltransportasi Soket default sebagai gantinya.
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 digunakan 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 Core.
Memulai
ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam template-generated Program.cs
berikut , WebApplication.CreateBuilder metode 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 Referensi cepat API minimal.
Sertifikat klien opsional
Untuk informasi tentang aplikasi yang harus melindungi subset aplikasi dengan sertifikat, lihat Sertifikat klien opsional.
Perilaku dengan debugger terlampir
Batas waktu habis dan tarif berikut tidak diberlakukan saat debugger dilampirkan ke Kestrel proses:
- KestrelServerLimits.KeepAliveTimeout
- KestrelServerLimits.RequestHeadersTimeout
- KestrelServerLimits.MinRequestBodyDataRate
- KestrelServerLimits.MinResponseDataRate
- IConnectionTimeoutFeature
- IHttpMinRequestBodyDataRateFeature
- IHttpMinResponseDataRateFeature
Sumber Daya Tambahan:
- Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel
- Sumber untuk
WebApplication.CreateBuilder
panggilan metode keUseKestrel
- Mengonfigurasi opsi untuk server web ASP.NET Core Kestrel
- Menggunakan HTTP/2 dengan server web ASP.NET Core Kestrel
- Kapan menggunakan proksi terbalik dengan server web ASP.NET Core Kestrel
- Pemfilteran host dengan server web ASP.NET Core Kestrel
- Memecahkan masalah dan mendebug proyek ASP.NET Core
- Menerapkan HTTPS di ASP.NET Core
- Konfigurasikan ASP.NET Core agar berfungsi dengan server proksi dan penyeimbang beban
- RFC 9110: Semantik HTTP (Bagian 7.2: Host dan :otoritas)
- Saat menggunakan soket UNIX di Linux, soket tidak secara otomatis dihapus pada penonaktifan aplikasi. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Catatan
Pada ASP.NET Core 5.0, Kestreltransportasi libuv sudah usang. Transportasi libuv tidak menerima pembaruan untuk mendukung platform OS baru, seperti Windows ARM64, dan akan dihapus dalam rilis mendatang. Hapus panggilan apa pun ke metode usang UseLibuv dan gunakan Kestreltransportasi Soket default sebagai gantinya.
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 digunakan 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 Core.
Melihat atau mengunduh kode sampel (cara mengunduh)
Memulai
ASP.NET templat proyek Core digunakan Kestrel secara default saat tidak dihosting dengan IIS. Dalam Program.cs
, ConfigureWebHostDefaults metode 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.
Sertifikat klien opsional
Untuk informasi tentang aplikasi yang harus melindungi subset aplikasi dengan sertifikat, lihat Sertifikat klien opsional.
Sumber Daya Tambahan:
- Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel
- Mengonfigurasi opsi untuk server web ASP.NET Core Kestrel
- Menggunakan HTTP/2 dengan server web ASP.NET Core Kestrel
- Kapan menggunakan proksi terbalik dengan server web ASP.NET Core Kestrel
- Pemfilteran host dengan server web ASP.NET Core Kestrel
- Memecahkan masalah dan mendebug proyek ASP.NET Core
- Menerapkan HTTPS di ASP.NET Core
- Konfigurasikan ASP.NET Core agar berfungsi dengan server proksi dan penyeimbang beban
- RFC 9110: Semantik HTTP (Bagian 7.2: Host dan :otoritas)
- Saat menggunakan soket UNIX di Linux, soket tidak secara otomatis dihapus pada aplikasi yang dimatikan. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Catatan
Pada ASP.NET Core 5.0, Kestreltransportasi libuv sudah usang. Transportasi libuv tidak menerima pembaruan untuk mendukung platform OS baru, seperti Windows ARM64, dan akan dihapus dalam rilis mendatang. Hapus panggilan apa pun ke metode usang UseLibuv dan gunakan Kestreltransportasi Soket default sebagai gantinya.
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 digunakan 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 Core.
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†
- Windows Server 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 dengan sendirinya 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 digunakan dalam konfigurasi proksi terbalik:
Konfigurasi, dengan atau tanpa server proksi terbalik, adalah konfigurasi hosting yang didukung.
Kestrel digunakan sebagai server edge tanpa server proksi terbalik tidak mendukung berbagi IP dan port yang sama di antara beberapa proses. Ketika Kestrel dikonfigurasi untuk mendengarkan port, Kestrel menangani semua lalu lintas untuk 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.
Proksi terbalik:
- Dapat membatasi area permukaan publik yang terekspos dari aplikasi yang dihostingnya.
- Berikan lapisan konfigurasi dan pertahanan tambahan.
- 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.
Peringatan
Hosting 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
, ConfigureWebHostDefaults metode 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.
Atur batasan pada Limits properti KestrelServerOptions kelas. Properti Limits
menyimpan instans KestrelServerLimits kelas.
Contoh berikut menggunakan Microsoft.AspNetCore.Server.Kestrel.Core namespace layanan:
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 File dapat memuat Kestrel konfigurasi dari appsettings.json
file atau appsettings.{Environment}.json
:
{
"Kestrel": {
"Limits": {
"MaxConcurrentConnections": 100,
"MaxConcurrentUpgradedConnections": 100
},
"DisableStringReuse": true
}
}
Catatan
KestrelServerOptions dan konfigurasi titik akhir dapat dikonfigurasi dari penyedia konfigurasi. Konfigurasi yang tersisa Kestrel harus dikonfigurasi dalam kode C#.
Gunakan salah satu pendekatan berikut:
Konfigurasikan Kestrel di
Startup.ConfigureServices
:Masukkan instans
IConfiguration
keStartup
dalam kelas . Contoh berikut mengasumsikan bahwa konfigurasi yang disuntikkan ditetapkan keConfiguration
properti .Di
Startup.ConfigureServices
, muat bagianKestrel
konfigurasi ke dalam Kestrelkonfigurasi: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
, muat bagianKestrel
konfigurasi ke dalam Kestrelkonfigurasi:// 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
Mendapatkan atau mengatur batas waktu tetap hidup. Default 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);
})
Koneksi klien maksimum
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 isi permintaan maksimum
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. Ada IsReadOnly
properti yang menunjukkan apakah MaxRequestBodySize
properti dalam status baca-saja, yang berarti terlambat untuk mengonfigurasi batas.
Saat aplikasi kehabisan proses di belakang Modul ASP.NET Core, Kestrelbatas 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 hilangnya koneksi yang awalnya mengirim data pada laju lambat karena mulai lambat 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 dalam sampel sebelumnya tidak ada untuk HttpContext.Features
permintaan HTTP/2 karena mengubah batas laju berdasarkan per permintaan umumnya tidak didukung untuk HTTP/2 karena dukungan protokol untuk multipleks permintaan. Namun, IHttpMinRequestBodyDataRateFeature masih ada HttpContext.Features
untuk permintaan HTTP/2, karena batas tingkat baca masih dapat dinonaktifkan sepenuhnya berdasarkan per permintaan dengan mengatur IHttpMinRequestBodyDataRateFeature.MinDataRate
ke null
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 header permintaan
Mendapatkan atau mengatur jumlah maksimum waktu yang dihabiskan server untuk menerima header permintaan. Default 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 tabel header
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 data isi permintaan maksimum dalam byte buffer server pada satu waktu yang dikumpulkan di semua permintaan (aliran) 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 buffer server pada satu waktu per permintaan (streaming). 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).
Trailer
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 diberikan keTrailer
header respons. Mendeklarasikan trailer respons bersifat opsional, tetapi disarankan. JikaDeclareTrailer
dipanggil, harus 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.
I/O Sinkron
AllowSynchronousIO mengontrol apakah I/O sinkron diizinkan untuk permintaan dan respons. Nilai defaultnya adalah false
.
Peringatan
Sejumlah besar pemblokiran operasi I/O sinkron dapat menyebabkan kelaparan 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 Mengambil alih konfigurasi.
Sertifikat pengembangan dibuat:
- Ketika .NET Core SDK diinstal.
- Alat dev-certs digunakan untuk membuat sertifikat.
Beberapa browser memerlukan pemberian izin eksplisit untuk mempercayai sertifikat pengembangan lokal.
Templat proyek mengonfigurasi aplikasi untuk dijalankan di HTTPS secara default dan menyertakan pengalihan HTTPS dan dukungan HSTS.
Panggil Listen atau ListenUnixSocket metode aktif 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>)
Menentukan konfigurasi Action
yang akan dijalankan untuk setiap titik akhir yang ditentukan. ConfigureEndpointDefaults
Panggilan beberapa kali menggantikan sebelumnya Action
dengan yang terakhir Action
ditentukan.
webBuilder.ConfigureKestrel(serverOptions =>
{
serverOptions.ConfigureEndpointDefaults(listenOptions =>
{
// Configure endpoint defaults
});
});
Catatan
Titik akhir yang dibuat dengan memanggil Listen sebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.
MengonfigurasiHttpsDefaults(Action<HttpsConnectionAdapterOptions>)
Menentukan konfigurasi Action
yang akan dijalankan untuk setiap titik akhir HTTPS. ConfigureHttpsDefaults
Panggilan beberapa kali menggantikan sebelumnya Action
dengan yang terakhir Action
ditentukan.
webBuilder.ConfigureKestrel(serverOptions =>
{
serverOptions.ConfigureHttpsDefaults(listenOptions =>
{
// certificate is an X509Certificate2
listenOptions.ServerCertificate = certificate;
});
});
Catatan
Titik akhir yang dibuat dengan memanggil Listen sebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.
Konfigurasikan(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:
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 mengonfigurasiHttpsConnectionAdapterOptions
. MengembalikanListenOptions
.storeName
adalah penyimpanan sertifikat untuk memuat sertifikat.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 mendengarkan dan http://localhost:5000
https://localhost:5001
(jika sertifikasi default tersedia).
Ganti sertifikat default dari konfigurasi
CreateDefaultBuilder
Configure(context.Configuration.GetSection("Kestrel"))
panggilan secara default untuk memuat Kestrel konfigurasi. 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 Default Sertifikat>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
danHttps
valid. - Parameter
Url
diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkatUrls
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 melaluiListen
bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi. - Bagian
Certificate
ini bersifat opsional. Jika bagianCertificate
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}"))
KestrelConfigurationLoader
mengembalikan dengan.Endpoint(string name, listenOptions => { })
metode yang dapat digunakan untuk melengkapi pengaturan 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
options.Configure(context.Configuration.GetSection("{SECTION}"))
lagi dengan bagian lain. Hanya konfigurasi terakhir yang digunakan, kecualiLoad
secara eksplisit dipanggil pada instans sebelumnya. Metapackage tidak memanggilLoad
sehingga bagian konfigurasi defaultnya dapat diganti. KestrelConfigurationLoader
mencerminkanListen
keluarga API dariKestrelServerOptions
sebagaiEndpoint
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:
- Berjalan pada kerangka kerja
netcoreapp2.1
target atau yang lebih baru. Padanet461
atau lebih baru, panggilan balik dipanggil tetapiname
selalunull
.name
juganull
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
Panggilan UseConnectionLogging untuk memancarkan log tingkat 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 titik akhir dengan ListenOptions. Gunakan API yang sama untuk mengonfigurasi pengaturan lain Kestrel untuk titik akhir tertentu.
Di Windows, sertifikat yang ditandatangani sendiri dapat dibuat menggunakan New-SelfSignedCertificate
cmdlet PowerShell. Untuk contoh yang tidak didukung, lihat UpdateIISExpressSSLForChrome.ps1
.
Di macOS, Linux, dan Windows, sertifikat dapat dibuat menggunakan OpenSSL.
Ikat 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
>http://unix:/tmp/{KESTREL SOCKET}:/;
location
>proxy_pass
.{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
Batasan
Konfigurasikan titik akhir dengan pendekatan berikut:
- UseUrls
--urls
argumen baris perintahurls
kunci konfigurasi hostASPNETCORE_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
danUseUrls
digunakan secara bersamaan,Listen
titik akhir mengambil alihUseUrls
titik akhir.
Konfigurasi titik akhir IIS
Saat menggunakan IIS, pengikatan URL untuk pengikatan penimpaan IIS diatur oleh atau Listen
UseUrls
. 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 nilai ke Protocols
properti dari HttpProtocols
enum.
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 Sebelumnya. |
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 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 pertukaran kunci ephemeral minimum:
- Kurva elips Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bit
- 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 memfilter jabat tangan TLS berdasarkan per 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 dengan 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
serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
panggilan secara default untuk memuat Kestrel konfigurasi.
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 nilai penimpaan kode yang ditetapkan oleh konfigurasi.
Awalan URL
Saat menggunakan UseUrls
argumen baris perintah, --urls
urls
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 IPv40.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 ataulocalhost
mengikat 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.Peringatan
Hosting dalam konfigurasi proksi terbalik memerlukan konfigurasi Middleware Header yang Diteruskan.
Nama host
localhost
dengan nomor port atau IP loopback dengan nomor porthttp://localhost:5000/ http://127.0.0.1:5000/ http://[::1]:5000/
Ketika
localhost
ditentukan, Kestrel upaya untuk 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 paket Microsoft.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 di/appsettings.json
appsettings.{Environment}.json
. Nilainya adalah daftar nama host yang dibatasi titik koma tanpa nomor port:
appsettings.json
:
{
"AllowedHosts": "example.com;localhost"
}
Catatan
Middleware Header yang Diteruskan juga memiliki AllowedHosts opsi. Middleware Header yang Diteruskan dan Middleware Pemfilteran Host memiliki fungsionalitas serupa untuk skenario yang berbeda. Pengaturan AllowedHosts
dengan Middleware Header yang Diteruskan sesuai saat Host
header tidak dipertahankan saat meneruskan permintaan dengan server proksi terbalik atau load balancer. Pengaturan AllowedHosts
dengan Middleware Pemfilteran Host sesuai ketika Kestrel digunakan sebagai server tepi yang menghadap publik atau ketika Host
header langsung diteruskan.
Untuk informasi selengkapnya tentang Middleware Header yang Diteruskan, lihat Mengonfigurasi ASP.NET Core untuk bekerja dengan server proksi dan load balancer.
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 intensif sumber daya. Oleh karena itu, Kestrel coba gunakan kembali koneksi sesuai protokol HTTP/1.1. Isi permintaan harus sepenuhnya digunakan untuk memungkinkan koneksi digunakan kembali. Aplikasi ini tidak selalu menggunakan isi permintaan, seperti POST
permintaan di mana server mengembalikan respons pengalihan atau 404. POST
Dalam kasus -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 pengurasan membuat tradeoff antara memungkinkan koneksi digunakan kembali dan waktu yang diperlukan untuk menguras data yang tersisa:
- Pengurasan memiliki batas waktu lima detik, yang tidak dapat dikonfigurasi.
- Jika semua data yang ditentukan oleh
Content-Length
header atauTransfer-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.
Abort
Panggilan harus jarang terjadi dan dicadangkan untuk kasus kesalahan yang parah, bukan kesalahan umum.- Hanya panggil
Abort
ketika masalah tertentu perlu diselesaikan. Misalnya, panggilAbort
jika klien berbahaya mencoba dataPOST
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).
- Hanya panggil
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. Bingkai 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:
- Saat menggunakan soket UNIX di Linux, soket tidak secara otomatis dihapus pada aplikasi yang dimatikan. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
- Memecahkan masalah dan mendebug proyek ASP.NET Core
- Menerapkan HTTPS di ASP.NET Core
- Konfigurasikan ASP.NET Core agar berfungsi dengan server proksi dan penyeimbang beban
- RFC 9110: Semantik HTTP (Bagian 7.2: Host dan :otoritas)
ASP.NET Core