Bagikan melalui

Kestrel server web di ASP.NET Core

  • Artikel

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.csberikut , 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:

Sumber Daya Tambahan:

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.csberikut , 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:

Sumber Daya Tambahan:

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:

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 pada 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 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, 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 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.

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:

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

    2. Di Startup.ConfigureServices, muat bagian Kestrel 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 bagian Kestrel 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

KeepAliveTimeout

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

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. 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

RequestHeadersTimeout

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 ke Trailer header respons. Mendeklarasikan trailer respons bersifat opsional, tetapi disarankan. Jika DeclareTrailer 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:

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 Actiondengan 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 Actiondengan 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.
  • configureOptionsAction adalah untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
  • 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

CreateDefaultBuilderConfigure(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 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}"))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, 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:

  • Berjalan pada kerangka kerja netcoreapp2.1 target 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

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 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, Listen titik akhir mengambil alih UseUrls 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

CreateDefaultBuilderserverOptions.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 UseUrlsargumen 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 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 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 port

    http://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.jsonappsettings.{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. POSTDalam 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 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.
  • Abort Panggilan 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. 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: