ASP.NET Core 中的 Kestrel 網頁伺服器實作Kestrel web server implementation in ASP.NET Core

05/04/2020

作者：Tom Dykstra、Chris Ross 和 Stephen HalterBy Tom Dykstra, Chris Ross, and Stephen Halter

Kestrel 是 ASP.NET Core 的跨平台網頁伺服器。Kestrel is a cross-platform web server for ASP.NET Core. Kestrel 是 ASP.NET Core 專案範本中預設包含和啟用的網頁伺服器。Kestrel is the web server that's included and enabled by default in ASP.NET Core project templates.

Kestrel 支援下列案例：Kestrel supports the following scenarios:

HTTPSHTTPS
除了 macOS) 之外， HTTP/2 (†HTTP/2 (except on macOS†)
用來啟用 WebSockets 的不透明升級Opaque upgrade used to enable WebSockets
Nginx 背後的高效能 Unix 通訊端Unix sockets for high performance behind Nginx

†未來版本的 macOS 上將會支援 HTTP/2。†HTTP/2 will be supported on macOS in a future release.

.NET Core 支援的所有平台和版本都支援 Kestrel。Kestrel is supported on all platforms and versions that .NET Core supports.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

開始使用Get started

ASP.NET Core 專案範本預設會使用 Kestrel。ASP.NET Core project templates use Kestrel by default. 在 Program.cs 中，此 ConfigureWebHostDefaults 方法會呼叫 UseKestrel ：In Program.cs, the ConfigureWebHostDefaults method calls 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>();
        });

如需建立主機的詳細資訊，請參閱的 設定主 控制項和預設建立器設定一節 ASP.NET Core 中的 .NET 泛型主機。For more information on building the host, see the Set up a host and Default builder settings sections of ASP.NET Core 中的 .NET 泛型主機.

其他資源Additional resources

設定 ASP.NET Core Kestrel web 伺服器的端點
設定 ASP.NET Core Kestrel web 伺服器的選項
搭配 ASP.NET Core Kestrel web 伺服器使用 HTTP/2
搭配 ASP.NET Core Kestrel web 伺服器使用反向 proxy 的時機
使用 ASP.NET Core Kestrel web 伺服器進行主機篩選
針對 ASP.NET Core 專案進行疑難排解和調試
在 ASP.NET Core 中強制使用 HTTPS
設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作
RFC 7230：訊息語法和路由 (第 5.4 節：主機)RFC 7230: Message Syntax and Routing (Section 5.4: Host)
在 Linux 上使用 UNIX 通訊端時，通訊端不會在應用程式關閉時自動刪除。When using UNIX sockets on Linux, the socket is not automatically deleted on app shut down. 如需詳細資訊，請參閱此 GitHub 問題。For more information, see this GitHub issue.

注意

從 ASP.NET Core 5.0，Kestrel 的 libuv 傳輸已淘汰。As of ASP.NET Core 5.0, Kestrel's libuv transport is obsolete. Libuv 傳輸不會接收更新來支援新的 OS 平臺（例如 Windows ARM64），並將在未來的版本中移除。The libuv transport doesn't receive updates to support new OS platforms, such as Windows ARM64, and will be removed in a future release. 移除任何對已淘汰方法的呼叫 UseLibuv ，並改為使用 Kestrel 的預設通訊端傳輸。Remove any calls to the obsolete UseLibuv method and use Kestrel's default Socket transport instead.

Kestrel 是 ASP.NET Core 的跨平台網頁伺服器。Kestrel is a cross-platform web server for ASP.NET Core. Kestrel 是 ASP.NET Core 專案範本中預設隨附的網頁伺服器。Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel 支援下列案例：Kestrel supports the following scenarios:

HTTPSHTTPS
用來啟用 WebSockets 的不透明升級Opaque upgrade used to enable WebSockets
Nginx 背後的高效能 Unix 通訊端Unix sockets for high performance behind Nginx
HTTP/2 (macOS 上除外†)HTTP/2 (except on macOS†)

†未來版本的 macOS 上將會支援 HTTP/2。†HTTP/2 will be supported on macOS in a future release.

.NET Core 支援的所有平台和版本都支援 Kestrel。Kestrel is supported on all platforms and versions that .NET Core supports.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

HTTP/2 支援HTTP/2 support

如果符合下列基本需求，則可以針對 ASP.NET Core 應用程式使用 HTTP/2：HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

作業系統†Operating system†
- Windows Server 2016/Windows 10 或更新版本‡Windows Server 2016/Windows 10 or later‡
- Linux 含 OpenSSL 1.0.2 或更新版本 (例如 Ubuntu 16.04 或更新版本)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
目標 Framework：.NET Core 2.2 或更新版本Target framework: .NET Core 2.2 or later
Application-Layer Protocol Negotiation (ALPN) 連線Application-Layer Protocol Negotiation (ALPN) connection
TLS 1.2 或更新版本連線TLS 1.2 or later connection

†未來版本的 macOS 上將會支援 HTTP/2。†HTTP/2 will be supported on macOS in a future release. ‡Kestrel 在 Windows Server 2012 R2 與 Windows 8.1 對 HTTP/2 的支援有限。‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. 支援有限的原因是這些作業系統上的支援 TLS 密碼編譯套件清單有限。Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. 可能需要使用橢圓曲線數位簽章演算法 (ECDSA) 產生的憑證來保護 TLS 連線。A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

如果已建立 HTTP/2 連線，HttpRequest.Protocol 會報告 HTTP/2。If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

從 .NET Core 3.0 開始，預設會啟用 HTTP/2。Starting with .NET Core 3.0, HTTP/2 is enabled by default. 如需組態的詳細資訊，請參閱 Kestrel 選項和 ListenOptions. 通訊協定一節。For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

何時搭配使用 Kestrel 與反向 ProxyWhen to use Kestrel with a reverse proxy

您可以單獨使用 Kestrel，或與 Internet Information Services (IIS)、Nginx 或 Apache 等「反向 Proxy 伺服器」搭配使用。Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. 反向 Proxy 伺服器會從網路接收 HTTP 要求，然後轉送到 Kestrel。A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel 用作邊緣 (網際網路對應) 網頁伺服器：Kestrel used as an edge (Internet-facing) web server:

Kestrel 不使用反向 Proxy 伺服器直接與網際網路通訊

Kestrel 用於反向 Proxy 組態中：Kestrel used in a reverse proxy configuration:

Kestrel 透過 IIS、Nginx 或 Apache 等反向 Proxy 伺服器間接與網際網路通訊

不論是否有反向 proxy 伺服器，設定都是支援的裝載設定。Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Kestrel 用作不需要反向 Proxy 伺服器的 Edge Server 時，不支援在多個處理序之間共用相同的 IP 和連接埠。Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. 當 Kestrel 設定為接聽連接埠時，Kestrel 會處理該連接埠的所有流量，而不論要求的 Host 標頭為何。When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. 可以共用連接埠的反向 Proxy 能夠在唯一的 IP 和連接埠上轉送要求給 Kestrel。A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

即使不需要反向 Proxy 伺服器，使用反向 Proxy 伺服器也是不錯的選擇。Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

反向 Proxy：A reverse proxy:

可以限制它所主控之應用程式的公開介面區。Can limit the exposed public surface area of the apps that it hosts.
提供額外的組態和防禦層。Provide an additional layer of configuration and defense.
能夠與現有基礎結構更好地整合。Might integrate better with existing infrastructure.
簡化負載平衡和安全通訊 (HTTPS) 組態。Simplify load balancing and secure communication (HTTPS) configuration. 只有反向 proxy 伺服器需要 x.509 憑證，而且該伺服器可以使用一般 HTTP 與內部網路上的應用程式伺服器進行通訊。Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.

ASP.NET Core apps 中的 KestrelKestrel in ASP.NET Core apps

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

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

若要在呼叫 ConfigureWebHostDefaults 之後提供額外的設定，請使用 ConfigureKestrel：To provide additional configuration after calling ConfigureWebHostDefaults, use ConfigureKestrel:

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

Kestrel 選項Kestrel options

Kestrel 網頁伺服器所含的條件約束組態選項，在網際網路對應部署方面特別有用。The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

請在 KestrelServerOptions 類別的 Limits 屬性上設定條件約束。Set constraints on the Limits property of the KestrelServerOptions class. Limits 屬性會保存 KestrelServerLimits 類別的執行個體。The Limits property holds an instance of the KestrelServerLimits class.

下列範例會使用 Microsoft.AspNetCore.Server.Kestrel.Core 命名空間；The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

在本文稍後所示的範例中，會在 c # 程式碼中設定 Kestrel 選項。In examples shown later in this article, Kestrel options are configured in C# code. 您也可以使用設定提供者來設定 Kestrel 選項。Kestrel options can also be set using a configuration provider. 例如，檔案設定提供者可以從或 Appsettings 載入 Kestrel 設定 appsettings.json 。環境}. json 檔案：For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

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

注意

KestrelServerOptions 和端點設定可從設定提供者進行設定。KestrelServerOptions and endpoint configuration are configurable from configuration providers. 其餘的 Kestrel 設定必須在 c # 程式碼中設定。Remaining Kestrel configuration must be configured in C# code.

使用下列 其中一 種方法：Use one of the following approaches:

設定 Kestrel in Startup.ConfigureServices ：Configure Kestrel in Startup.ConfigureServices:
1. 將的實例插入 IConfiguration 至 Startup 類別。Inject an instance of IConfiguration into the Startup class. 下列範例假設將插入的設定指派給 Configuration 屬性。The following example assumes that the injected configuration is assigned to the Configuration property.
2. 在中 Startup.ConfigureServices ，將 Kestrel configuration 區段載入 Kestrel 的設定：In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:
```
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)
    {
        ...
    }
}
```

設定 Kestrel 建立主機時：Configure Kestrel when building the host:

在 Program.cs 中，將 Kestrel Configuration 區段載入 Kestrel 的設定中：In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

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

上述兩種方法都可搭配任何設定提供者使用。Both of the preceding approaches work with any configuration provider.

Keep-alive 逾時Keep-alive timeout

KeepAliveTimeout

取得或設定 Keep-alive 逾時 (英文)。Gets or sets the keep-alive timeout. 預設為 2 分鐘。Defaults to 2 minutes.

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

用戶端連線數目上限Maximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

可以使用下列程式碼，針對整個應用程式設定同時開啟的 TCP 連線數目上限：The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Limits.MaxConcurrentConnections = 100;
    serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
    serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
    serverOptions.Limits.MinRequestBodyDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Limits.MinResponseDataRate =
        new MinDataRate(bytesPerSecond: 100, 
            gracePeriod: TimeSpan.FromSeconds(10));
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testPassword");
        });
    serverOptions.Limits.KeepAliveTimeout = 
        TimeSpan.FromMinutes(2);
    serverOptions.Limits.RequestHeadersTimeout = 
        TimeSpan.FromMinutes(1);
})

已經從 HTTP 或 HTTPS 升級為另一個通訊協定 (例如，在 WebSocket 要求中) 的連線，有其個別限制。There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). 升級連線之後，它不會納入 MaxConcurrentConnections 限制。After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

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

連線數目上限預設為無限制 (null)。The maximum number of connections is unlimited (null) by default.

要求主體大小上限Maximum request body size

MaxRequestBodySize

預設的要求主體大小上限是 30,000,000 個位元組，大約 28.6 MB。The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

若要覆寫 ASP.NET Core MVC 應用程式中的限制，建議的方式是在動作方法上使用 RequestSizeLimitAttribute屬性：The recommended approach to override the limit in an ASP.NET Core MVC app is to use the RequestSizeLimitAttribute attribute on an action method:

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

以下範例會示範如何設定應用程式、每個要求的條件約束：Here's an example that shows how to configure the constraint for the app on every request:

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

覆寫中介軟體中特定要求的設定：Override the setting on a specific request in 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));
    }

如果應用程式在應用程式開始讀取要求之後設定要求的限制，則會擲回例外狀況。An exception is thrown if the app configures the limit on a request after the app has started to read the request. 有一個 IsReadOnly 屬性會指出 MaxRequestBodySize 屬性處於唯讀狀態，這表示要設定限制已經太遲。There's an IsReadOnly property that indicates if the MaxRequestBodySize property is in read-only state, meaning it's too late to configure the limit.

當應用程式是在 ASP.NET Core 模組後方於處理序外執行時，Kestrel 的要求本文大小限制將會被停用，因為 IIS 已經設定限制。When an app is run out-of-process behind the ASP.NET Core Module, Kestrel's request body size limit is disabled because IIS already sets the limit.

要求主體資料速率下限Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

如果資料是以指定的速率 (位元組/秒) 傳入，Kestrel 會每秒檢查一次。Kestrel checks every second if data is arriving at the specified rate in bytes/second. 如果速率降到低於最小值，則連接會超時。寬限期是 Kestrel 讓用戶端提高其傳送速率的時間量（最小值）;在這段時間內不會檢查速率。If the rate drops below the minimum, the connection is timed out. The grace period is the amount of time that Kestrel gives the client to increase its send rate up to the minimum; the rate isn't checked during that time. 寬限期可協助避免中斷連線，這是由於 TCP 緩慢啟動而一開始以低速傳送資料所造成。The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

預設速率下限為 240 個位元組/秒，寬限期為 5 秒。The default minimum rate is 240 bytes/second with a 5 second grace period.

速率下限也適用於回應。A minimum rate also applies to the response. 除了屬性中具有 RequestBody 或 Response 以及介面名稱之外，用來設定要求限制和回應限制的程式碼都相同。The code to set the request limit and the response limit is the same except for having RequestBody or Response in the property and interface names.

以下範例示範如何在 Program.cs 中設定資料速率下限：Here's an example that shows how to configure the minimum data rates in 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);
})

覆寫中介軟體中每個要求的最小速率限制：Override the minimum rate limits per request in 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));
    }

因為通訊協定對要求多工的支援，所以 HTTP/2 一般不支援以每一要求基礎修改速率限制，進而使先前範例中所參考的 IHttpMinResponseDataRateFeature 不會出現在 HTTP/2 要求的 HttpContext.Features 中。The IHttpMinResponseDataRateFeature referenced in the prior sample is not present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis is generally not supported for HTTP/2 due to the protocol's support for request multiplexing. 不過，IHttpMinRequestBodyDataRateFeature 仍存在 HTTP/2 要求的 HttpContext.Features您仍能透過將 IHttpMinRequestBodyDataRateFeature.MinDataRate 設定為 null (即使是針對 HTTP/2 要求)，以個別要求基礎來「完全停用」讀取素率限制。However, the IHttpMinRequestBodyDataRateFeature is still present HttpContext.Features for HTTP/2 requests, because the read rate limit can still be disabled entirely on a per-request basis by setting IHttpMinRequestBodyDataRateFeature.MinDataRate to null even for an HTTP/2 request. 嘗試讀取 IHttpMinRequestBodyDataRateFeature.MinDataRate 或嘗試將它設定為 null 以外的值將會導致擲回 NotSupportedException (假設要求是 HTTP/2 要求)。Attempting to read IHttpMinRequestBodyDataRateFeature.MinDataRate or attempting to set it to a value other than null will result in a NotSupportedException being thrown given an HTTP/2 request.

透過 KestrelServerOptions.Limits 設定的全伺服器速率限制皆仍套用至 HTTP/1.x 及 HTTP/2 連線。Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

要求標頭逾時Request headers timeout

RequestHeadersTimeout

取得或設定伺服器花費在接收要求標頭的時間上限。Gets or sets the maximum amount of time the server spends receiving request headers. 預設為 30 秒。Defaults to 30 seconds.

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

每個連線的資料流數目上限Maximum streams per connection

Http2.MaxStreamsPerConnection 會限制每個 HTTP/2 連線的同時要求資料流數目。Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. 超出的資料流會被拒絕。Excess streams are refused.

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

預設值是 100。The default value is 100.

標頭表格大小Header table size

HPACK 解碼器可解壓縮 HTTP/2 連線的 HTTP 標頭。The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize 會限制 HPACK 解碼器所使用的標頭壓縮表格大小。Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. 這個值是以八位元提供，而且必須大於零 (0)。The value is provided in octets and must be greater than zero (0).

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

預設值為 4096。The default value is 4096.

框架大小上限Maximum frame size

Http2.MaxFrameSize 指出伺服器接收或傳送之 HTTP/2 連接框架承載的允許大小上限。Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. 這個值是以八位元提供，而且必須介於 2^14 (16,384) 到 2^24-1 (16,777,215) 之間。The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

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

預設值為 2^14 (16,384)。The default value is 2^14 (16,384).

要求標頭大小上限Maximum request header size

Http2.MaxRequestHeaderFieldSize 以八位元表示要求標頭值的允許大小上限。Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. 這項限制適用于其壓縮和未壓縮標記法中的名稱和值。This limit applies to both name and value in their compressed and uncompressed representations. 此值必須大於零 (0)。The value must be greater than zero (0).

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

預設值為 8,192。The default value is 8,192.

初始連線視窗大小Initial connection window size

Http2.InitialConnectionWindowSize 會以位元組表示伺服器緩衝每個連線之所有要求 (資料流) 單次彙總的要求內容資料上限。Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. 要求也皆受 Http2.InitialStreamWindowSize 所限制。Requests are also limited by Http2.InitialStreamWindowSize. 此值必須大於或等於 65,535，且小於 2^31 (2,147,483,648)。The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

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

預設值為 128 KB (131,072)。The default value is 128 KB (131,072).

初始資料流視窗大小Initial stream window size

Http2.InitialStreamWindowSize 會以位元組表示每個要求 (資料流) 單次伺服器緩衝的要求內容資料上限。Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). 要求也皆受 Http2.InitialConnectionWindowSize 所限制。Requests are also limited by Http2.InitialConnectionWindowSize. 此值必須大於或等於 65,535，且小於 2^31 (2,147,483,648)。The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

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

預設值為 96 KB (98,304)。The default value is 96 KB (98,304).

預告片Trailers

HTTP 結尾與 HTTP 標頭類似，不同之處在于它們會在傳送回應主體之後傳送。HTTP Trailers are similar to HTTP Headers, except they are sent after the response body is sent. 針對 IIS 和 HTTP.SYS，只支援 HTTP/2 回應尾端。For IIS and HTTP.SYS, only HTTP/2 response trailers are supported.

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

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

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

在上述的範例程式碼中：In the preceding example code:

SupportsTrailers 確保回應支援尾端。SupportsTrailers ensures that trailers are supported for the response.
DeclareTrailer 將指定的尾端名稱加入至 Trailer 回應標頭。DeclareTrailer adds the given trailer name to the Trailer response header. 宣告回應的尾端是選擇性的，但建議使用。Declaring a response's trailers is optional, but recommended. 如果 DeclareTrailer 呼叫，則必須在傳送回應標頭之前。If DeclareTrailer is called, it must be before the response headers are sent.
AppendTrailer 附加尾端。AppendTrailer appends the trailer.

重設Reset

Reset 可讓伺服器重設具有指定錯誤碼的 HTTP/2 要求。Reset allows for the server to reset a HTTP/2 request with a specified error code. 重設要求會視為已中止。A reset request is considered aborted.

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

Reset 在上述程式碼範例中，指定 INTERNAL_ERROR 錯誤碼。Reset in the preceding code example specifies the INTERNAL_ERROR error code. 如需有關 HTTP/2 錯誤碼的詳細資訊，請造訪 HTTP/2 規格錯誤碼一節。For more information about HTTP/2 error codes, visit the HTTP/2 specification error code section.

同步 I/OSynchronous I/O

AllowSynchronousIO 控制要求和回應是否允許同步 i/o。AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. 預設值是 false。The default value is false.

警告

大量封鎖同步 i/o 作業可能會導致執行緒集區耗盡，而使應用程式無回應。A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. 只有 AllowSynchronousIO 在使用不支援非同步 i/o 的程式庫時才啟用。Only enable AllowSynchronousIO when using a library that doesn't support asynchronous I/O.

下列範例會啟用同步 i/o：The following example enables synchronous I/O:

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

如需其他 Kestrel 選項和限制的資訊，請參閱：For information about other Kestrel options and limits, see:

端點組態Endpoint configuration

ASP.NET Core 預設會繫結至：By default, ASP.NET Core binds to:

http://localhost:5000
https://localhost:5001 (當有本機開發憑證存在時)https://localhost:5001 (when a local development certificate is present)

使用以下各項指定 URL：Specify URLs using the:

ASPNETCORE_URLS 環境變數。ASPNETCORE_URLS environment variable.
--urls 命令列引數。--urls command-line argument.
urls 主機組態索引鍵。urls host configuration key.
UseUrls 擴充方法。UseUrls extension method.

使用這些方法提供的值可以是一或多個 HTTP 和 HTTPS 端點 (如果有預設憑證可用則為 HTTPS)。The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). 將值設定為以分號分隔的清單 (例如，"Urls": "http://localhost:8000;http://localhost:8001")。Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

如需有關這些方法的詳細資訊，請參閱伺服器 URL 和覆寫設定。For more information on these approaches, see Server URLs and Override configuration.

開發憑證會建立於：A development certificate is created:

已安裝 .NET Core SDK 時。When the .NET Core SDK is installed.
dev-certs 工具用來建立憑證。The dev-certs tool is used to create a certificate.

某些瀏覽器需要授與明確的許可權，以信任本機開發憑證。Some browsers require granting explicit permission to trust the local development certificate.

專案範本預設會將應用程式設定為在 HTTPS 上執行，並包含 Https 重新導向和 HSTS 支援。Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

請在 KestrelServerOptions 上呼叫 Listen 或 ListenUnixSocket 方法，來為 Kestrel 設定 URL 首碼和連接埠。Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

UseUrls、--urls 命令列引數、urls 主機組態索引鍵和 ASPNETCORE_URLS 環境變數同樣有效，但卻有本節稍後註明的限制 (針對 HTTPS 端點組態必須有預設憑證可用)。UseUrls, the --urls command-line argument, urls host configuration key, and the ASPNETCORE_URLS environment variable also work but have the limitations noted later in this section (a default certificate must be available for HTTPS endpoint configuration).

KestrelServerOptions 配置：KestrelServerOptions configuration:

ConfigureEndpointDefaults (動作 <ListenOptions>) ConfigureEndpointDefaults(Action<ListenOptions>)

指定組態 Action 以針對每個指定端點執行。Specifies a configuration Action to run for each specified endpoint. 呼叫 ConfigureEndpointDefaults 多次會以最後一個指定的 Action 取代之前的 Action。Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

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

注意

在呼叫之前呼叫所建立的端點 Listen ConfigureEndpointDefaults ，將不會套用預設值。Endpoints created by calling Listen before calling ConfigureEndpointDefaults won't have the defaults applied.

ConfigureHttpsDefaults (動作 <HttpsConnectionAdapterOptions>) ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

指定組態 Action 以針對每個 HTTPS 端點執行。Specifies a configuration Action to run for each HTTPS endpoint. 呼叫 ConfigureHttpsDefaults 多次會以最後一個指定的 Action 取代之前的 Action。Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

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

注意

在呼叫之前呼叫所建立的端點 Listen ConfigureHttpsDefaults ，將不會套用預設值。Endpoints created by calling Listen before calling ConfigureHttpsDefaults won't have the defaults applied.

Configure(IConfiguration)Configure(IConfiguration)

建立設定載入器來設定以 IConfiguration 作為輸入的 Kestrel。Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. 組態的範圍必須限於 Kestrel 的組態區段。The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

設定 Kestrel 使用 HTTPS。Configure Kestrel to use HTTPS.

ListenOptions.UseHttps 延伸模組：ListenOptions.UseHttps extensions:

UseHttps：設定 Kestrel 以搭配預設憑證使用 HTTPS。UseHttps: Configure Kestrel to use HTTPS with the default certificate. 如果未設定預設憑證，會擲回例外狀況。Throws an exception if no default certificate is configured.
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 參數：ListenOptions.UseHttps parameters:

filename 是憑證檔案的路徑和檔案名稱，它相對於包含應用程式內容檔案的目錄。filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
password 是存取 X.509 憑證資料所需的密碼。password is the password required to access the X.509 certificate data.
configureOptions 是設定 HttpsConnectionAdapterOptions 的 Action。configureOptions is an Action to configure the HttpsConnectionAdapterOptions. 傳回 ListenOptions。Returns the ListenOptions.
storeName 是要從中載入憑證的憑證存放區。storeName is the certificate store from which to load the certificate.
subject 是憑證的主體名稱。subject is the subject name for the certificate.
allowInvalid 表示是否應該考慮無效的憑證，例如自我簽署憑證。allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
location 是要從中載入憑證的存放區位置。location is the store location to load the certificate from.
serverCertificate 是 X.509 憑證。serverCertificate is the X.509 certificate.

在生產環境中，必須明確設定 HTTPS。In production, HTTPS must be explicitly configured. 至少必須提供預設憑證。At a minimum, a default certificate must be provided.

支援的組態描述如下：Supported configurations described next:

無組態No configuration
從組態取代預設憑證Replace the default certificate from configuration
變更程式碼中的預設值Change the defaults in code

無組態No configuration

Kestrel 會接聽 http://localhost:5000 和 https://localhost:5001 (如果預設憑證可用的話)。Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

從組態取代預設憑證Replace the default certificate from configuration

CreateDefaultBuilder 預設會呼叫 Configure(context.Configuration.GetSection("Kestrel")) 以載入 Kestrel 設定。CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. Kestrel 可以使用預設的 HTTPS 應用程式設定組態結構描述。A default HTTPS app settings configuration schema is available for Kestrel. 設定多個端點，包括 URL 和要使用的憑證－從磁碟上的檔案，或是從憑證存放區。Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

在下列 appsettings.json 範例中：In the following appsettings.json example:

將 AllowInvalid 設定為 true，允許使用無效的憑證 (例如，自我簽署憑證)。Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
任何未指定憑證 (接下來範例中的 HttpsDefaultCert) 的 HTTPS 端點會回復為 [憑證][預設] > 下定義的憑證或開發憑證。Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.

{
  "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>"
      }
    }
  }
}

除了針對任何憑證節點使用 [路徑] 和 [密碼]，還可以使用憑證存放區欄位指定憑證。An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. 例如，您可以將憑證 > 預設憑證指定為：For example, the Certificates > Default certificate can be specified as:

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

結構描述附註：Schema notes:

端點名稱不區分大小寫。Endpoints names are case-insensitive. 例如，HTTPS 和 Https 都有效。For example, HTTPS and Https are valid.
Url 參數對每個端點而言都是必要的。The Url parameter is required for each endpoint. 此參數的格式等同於最上層 Urls 組態參數，但是它限制為單一值。The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
這些端點會取代最上層 Urls 組態中定義的端點，而不是新增至其中。These endpoints replace those defined in the top-level Urls configuration rather than adding to them. 透過 Listen 在程式碼中定義的端點，會與組態區段中定義的端點累計。Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
Certificate 區段是選擇性的。The Certificate section is optional. 如果未指定 Certificate 區段，則會使用先前案例中所定義的預設值。If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. 如果沒有預設值可供使用，伺服器就會擲回例外狀況，且無法啟動。If no defaults are available, the server throws an exception and fails to start.
Certificate區段同時支援路徑 – 密碼和主體 – 存放區 憑證。The Certificate section supports both Path–Password and Subject–Store certificates.
可以用這種方式定義任何數目的端點，只要它們不會導致連接埠衝突即可。Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
options.Configure(context.Configuration.GetSection("{SECTION}")) 會傳回 KestrelConfigurationLoader 與 .Endpoint(string name, listenOptions => { }) 方法，此方法可用來補充已設定的端點設定：options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:

webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader 可以直接存取，以繼續逐一查看現有的載入器，例如所提供的載入器 CreateDefaultBuilder 。KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

您可以在方法的選項中使用每個端點的設定區段， Endpoint 以便讀取自訂設定。The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
可以藉由使用另一個區段再次呼叫 options.Configure(context.Configuration.GetSection("{SECTION}")) 而載入多個組態。Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. 只會使用最後一個組態，除非在先前的執行個體上已明確呼叫 Load。Only the last configuration is used, unless Load is explicitly called on prior instances. 中繼套件不會呼叫 Load，如此可能會取代其預設組態區段。The metapackage doesn't call Load so that its default configuration section may be replaced.
KestrelConfigurationLoader 會將來自 KestrelServerOptions 的 API 的 Listen 系列鏡像為 Endpoint 多載，所以可在相同的位置設定程式碼和設定端點。KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. 這些多載不使用名稱，並且只使用來自組態的預設組態。These overloads don't use names and only consume default settings from configuration.

變更程式碼中的預設值Change the defaults in code

ConfigureEndpointDefaults 和 ConfigureHttpsDefaults 可以用來變更 ListenOptions 和 HttpsConnectionAdapterOptions 的預設設定，包括覆寫先前案例中指定的預設憑證。ConfigureEndpointDefaults and ConfigureHttpsDefaults can be used to change default settings for ListenOptions and HttpsConnectionAdapterOptions, including overriding the default certificate specified in the prior scenario. ConfigureEndpointDefaults 和 ConfigureHttpsDefaults 應該在設定任何端點之前呼叫。ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

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

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

SNI 的 Kestrel 支援Kestrel support for SNI

伺服器名稱指示 (SNI) 可以用於在相同的 IP 位址和連接埠上裝載多個網域。Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. SNI 若要運作，用戶端會在 TLS 信號交換期間傳送安全工作階段的主機名稱給伺服器，讓伺服器可以提供正確的憑證。For SNI to function, the client sends the host name for the secure session to the server during the TLS handshake so that the server can provide the correct certificate. 用戶端在 TLS 信號交換之後的安全工作階段期間，會使用所提供的憑證與伺服器進行加密通訊。The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel 透過 ServerCertificateSelector 回呼來支援 SNI。Kestrel supports SNI via the ServerCertificateSelector callback. 回呼會針對每個連線叫用一次，允許應用程式檢查主機名稱並選取適當的憑證。The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

SNI 支援需要：SNI support requires:

在目標 framework netcoreapp2.1 或更新版本上執行。Running on target framework netcoreapp2.1 or later. 在 net461 或更新版本中，會叫用回呼，但 name 一律為 null 。On net461 or later, the callback is invoked but the name is always null. 如果用戶端不在 TLS 信號交換中提供主機名稱參數，則 name 也是 null。The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
所有網站都在相同的 Kestrel 執行個體上執行。All websites run on the same Kestrel instance. 在不使用反向 Proxy 的情況下，Kestrel 不支援跨多個執行個體共用 IP 位址和連接埠。Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase);
            certs["localhost"] = localhostCert;
            certs["example.com"] = exampleCert;
            certs["sub.example.com"] = subExampleCert;

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

連接記錄Connection logging

呼叫 UseConnectionLogging 以發出連接上位元組層級通訊的 Debug 層級記錄。Call UseConnectionLogging to emit Debug level logs for byte-level communication on a connection. 連線記錄有助於疑難排解低層級通訊中的問題，例如在 TLS 加密期間和 proxy 後方。Connection logging is helpful for troubleshooting problems in low-level communication, such as during TLS encryption and behind proxies. 如果 UseConnectionLogging 之前放置 UseHttps ，則會記錄加密的流量。If UseConnectionLogging is placed before UseHttps, encrypted traffic is logged. 如果 UseConnectionLogging 放置在之後 UseHttps ，則會記錄解密的流量。If UseConnectionLogging is placed after UseHttps, decrypted traffic is logged.

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

繫結至 TCP 通訊端Bind to a TCP socket

Listen 方法會繫結至 TCP 通訊端，而選項 Lambda 則會允許 X.509 憑證設定：The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

此範例使用 ListenOptions來為端點設定 HTTPS。The example configures HTTPS for an endpoint with ListenOptions. 若要設定特定端點的其他 Kestrel 設定，請使用相同的 API。Use the same API to configure other Kestrel settings for specific endpoints.

在 Windows 中，可使用 New-SelfSignedCertificate PowerShell cmdlet 建立自我簽署的憑證。On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. 如需不支援的範例，請參閱 UpdateIISExpressSSLForChrome.ps1 (英文)。For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

在 macOS、Linux 和 Windows 上，可以使用 OpenSSL (英文) 建立憑證。On macOS, Linux, and Windows, certificates can be created using OpenSSL.

繫結至 Unix 通訊端Bind to a Unix socket

請使用 ListenUnixSocket 在 Unix 通訊端上進行接聽以改善 Nginx 的效能，如此範例所示：Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})

在 Nginx 設定檔中，將 server > location > proxy_pass 專案設定為 http://unix:/tmp/{KESTREL SOCKET}:/; 。In the Nginx configuration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} 這是提供給 (的通訊端名稱 ListenUnixSocket ，例如 kestrel-test.sock 上述範例) 。{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
確定 Nginx (可寫入通訊端，例如 chmod go+w /tmp/kestrel-test.sock) 。Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

連接埠 0Port 0

指定連接埠號碼 0 時，Kestrel 會動態繫結至可用的連接埠。When the port number 0 is specified, Kestrel dynamically binds to an available port. 下列範例示範如何判斷 Kestrel 在執行階段實際上繫結至哪一個連接埠：The following example shows how to determine which port Kestrel actually bound at 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>");
    });
}

當應用程式執行時，主控台視窗輸出會指出可以連線到應用程式的動態連接埠：When the app is run, the console window output indicates the dynamic port where the app can be reached:

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

限制Limitations

使用下列方法來設定端點：Configure endpoints with the following approaches:

UseUrls
--urls 命令列引數--urls command-line argument
urls 主機組態索引鍵urls host configuration key
ASPNETCORE_URLS 環境變數ASPNETCORE_URLS environment variable

要讓程式碼使用 Kestrel 以外的伺服器，這些方法會很有用。These methods are useful for making code work with servers other than Kestrel. 不過，請注意下列限制：However, be aware of the following limitations:

HTTPS 無法與這些方法搭配使用，除非在 HTTPS 端點設定中提供預設憑證 (例如，使用 KestrelServerOptions 設定或設定檔，如本主題稍早所示)。HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
當同時使用 Listen 和 UseUrls 方法時，Listen 端點會覆寫 UseUrls 端點。When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS 端點設定IIS endpoint configuration

使用 IIS 時，IIS 覆寫繫結的 URL 繫結是由 Listen 或 UseUrls 設定。When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. 如需詳細資訊，請參閱 ASP.NET Core 模組主題。For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

Protocols 屬性會建立在連線端點上或針對伺服器啟用的 HTTP 通訊協定 (HttpProtocols)。The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. 從 HttpProtocols 列舉中指派一個值給 Protocols 屬性。Assign a value to the Protocols property from the HttpProtocols enum.

`HttpProtocols` 列舉值`HttpProtocols` enum value	允許的連線通訊協定Connection protocol permitted
`Http1`	僅限 HTTP/1.1。HTTP/1.1 only. 可在具有或沒有 TLS 的情況下使用。Can be used with or without TLS.
`Http2`	僅限 HTTP/2。HTTP/2 only. 只有在用戶端支援先備知識模式時，才可以在沒有 TLS 的情況下使用。May be used without TLS only if the client supports a Prior Knowledge mode.
`Http1AndHttp2`	HTTP/1.1 和 HTTP/2。HTTP/1.1 and HTTP/2. HTTP/2 要求用戶端在 TLS 應用層通訊協定協商中選取 HTTP/2， (ALPN) 交握;否則，連接預設為 HTTP/1.1。HTTP/2 requires the client to select HTTP/2 in the TLS Application-Layer Protocol Negotiation (ALPN) handshake; otherwise, the connection defaults to HTTP/1.1.

ListenOptions.Protocols任何端點的預設值為 HttpProtocols.Http1AndHttp2 。The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

HTTP/2 的 TLS 限制：TLS restrictions for HTTP/2:

TLS 1.2 版或更新版本TLS version 1.2 or later
已停用重新交涉Renegotiation disabled
已停用壓縮Compression disabled
暫時金鑰交換大小下限：Minimum ephemeral key exchange sizes:
- 橢圓曲線 Diffie-Hellman (>ECDHE) [ RFC4492 ] ：最少224位Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
- 有限的欄位 Diffie-Hellman (DHE) [ TLS12 ] ：最低2048位Finite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
不禁止加密套件。Cipher suite not prohibited.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256[TLS-ECDHE]預設支援使用 P-256 橢圓曲線 [ FIPS186 ] 。TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

下列範例會允許連接埠 8000 上的 HTTP/1.1 和 HTTP/2 連線。The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. 這些連線使用提供的憑證受到 TLS 保護：Connections are secured by TLS with a supplied certificate:

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

若有需要，請使用連線中介軟體針對特定加密篩選每個連接的 TLS 交握。Use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers if required.

下列範例 NotSupportedException 會針對應用程式不支援的任何加密演算法擲回。The following example throws NotSupportedException for any cipher algorithm that the app doesn't support. 或者，將 ITlsHandshakeFeature 定義和比較成可接受的加密套件清單。Alternatively, define and compare ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher suites.

CipherAlgorithmType 不會使用加密。 Null 加密演算法。No encryption is used with a CipherAlgorithmType.Null cipher algorithm.

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

您也可以透過 lambda 設定連接篩選 IConnectionBuilder ：Connection filtering can also be configured via an 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();
        });
    });
});

在 Linux 上， CipherSuitesPolicy 可用來篩選每個連接的 TLS 交握：On Linux, CipherSuitesPolicy can be used to filter TLS handshakes on a per-connection basis:

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

從設定進行通訊協定設定Set the protocol from configuration

CreateDefaultBuilder 預設會呼叫 serverOptions.Configure(context.Configuration.GetSection("Kestrel")) 以載入 Kestrel 設定。CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

下列 appsettings.json 範例會建立 HTTP/1.1 作為所有端點的預設連接通訊協定：The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

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

下列 appsettings.json 範例會建立特定端點的 HTTP/1.1 連接通訊協定：The following appsettings.json example establishes the HTTP/1.1 connection protocol for a specific endpoint:

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

程式碼中指定的通訊協定會覆寫設定所設定的值。Protocols specified in code override values set by configuration.

URL 前置詞URL prefixes

使用 UseUrls、--urls 命令列引數、urls 主機組態索引鍵或 ASPNETCORE_URLS 環境變數時，URL 前置詞可以採用下列任一格式。When using UseUrls, --urls command-line argument, urls host configuration key, or ASPNETCORE_URLS environment variable, the URL prefixes can be in any of the following formats.

只有 HTTP URL 前置詞有效。Only HTTP URL prefixes are valid. 使用 UseUrls 來設定 URL 繫結時，Kestrel 不支援 HTTPS。Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

IPv4 位址與連接埠號碼IPv4 address with port number
```
http://65.55.39.10:80/
```
0.0.0.0 是繫結至所有 IPv4 位址的特殊情況。0.0.0.0 is a special case that binds to all IPv4 addresses.
IPv6 位址與連接埠號碼IPv6 address with port number
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] 是相當於 IPv4 0.0.0.0 的 IPv6 對等項目。[::] is the IPv6 equivalent of IPv4 0.0.0.0.
主機名稱與連接埠號碼Host name with port number
```
http://contoso.com:80/
http://*:80/
```
主機名稱 * 和 + 並不特殊。Host names, *, and +, aren't special. 無法辨識為有效 IP 位址或 localhost 的任何項目，都會繫結至所有 IPv4 和 IPv6 IP。Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. 若要在相同連接埠上將不同的主機名稱繫結至不同的 ASP.NET Core 應用程式，請使用 HTTP.sys 或反向 Proxy 伺服器 (例如 IIS、Nginx 或 Apache)。To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.
主機 localhost 名稱與連接埠號碼，或回送 IP 與連接埠號碼Host localhost name with port number or loopback IP with port number
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
如果指定 localhost，Kestrel 會嘗試同時繫結至 IPv4 和 IPv6 回送介面。When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. 如果所要求的連接埠在任一個回送介面上由另一個服務使用，則 Kestrel 無法啟動。If the requested port is in use by another service on either loopback interface, Kestrel fails to start. 如果任一回送介面由於任何其他原因 (最常見的原因是不支援 IPv6) 無法使用，Kestrel 就會記錄警告。If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

主機篩選Host filtering

雖然 Kestrel 根據前置詞來支援組態，例如 http://example.com:5000，Kestrel 大多會忽略主機名稱。While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. 主機 localhost 是特殊情況，用來繫結到回送位址。Host localhost is a special case used for binding to loopback addresses. 任何非明確 IP 位址的主機，會繫結至所有公用 IP 位址。Any host other than an explicit IP address binds to all public IP addresses. Host 標頭未驗證。Host headers aren't validated.

因應措施是使用主機篩選中介軟體。As a workaround, use Host Filtering Middleware. 主機篩選中介軟體是由 AspNetCore HostFiltering 套件所提供，該套件是針對 ASP.NET Core 應用程式隱含提供的。Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. 中介軟體是由 CreateDefaultBuilder 所新增，它會呼叫 AddHostFiltering：The middleware is added by CreateDefaultBuilder, which calls 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>();
}

預設停用主機篩選中介軟體。Host Filtering Middleware is disabled by default. 若要啟用中介軟體，請 AllowedHosts 在 appsettings.json / appsettings 中定義 <EnvironmentName> 金鑰。json。To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. 此值是以分號分隔的主機名稱清單，不含連接埠號碼：The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

注意

轉送的標頭中介軟體也有 AllowedHosts 選項。Forwarded Headers Middleware also has an AllowedHosts option. 在不同的案例中，轉送標頭中介軟體和主機篩選中介軟體有類似的功能。Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. 當不保留 Host 標頭，卻使用反向 Proxy 伺服器或負載平衡器轉送要求時，可使用轉送標頭中介軟體設定 AllowedHosts。Setting AllowedHosts with Forwarded Headers Middleware is appropriate when the Host header isn't preserved while forwarding requests with a reverse proxy server or load balancer. 當使用 Kestrel 作為公眾對應 Edge Server，或直接轉送 Host 標頭時，可使用主機篩選中介軟體設定 AllowedHosts。Setting AllowedHosts with Host Filtering Middleware is appropriate when Kestrel is used as a public-facing edge server or when the Host header is directly forwarded.

如需轉送標頭中介軟體的詳細資訊，請參閱設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作。For more information on Forwarded Headers Middleware, see 設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作.

Libuv 傳輸設定Libuv transport configuration

對於需要使用 Libuv () 的專案 UseLibuv ：For projects that require the use of Libuv (UseLibuv):

將套件的相依性新增 Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv 至應用程式的專案檔案：Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:
```
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />
```

UseLibuv在上呼叫 IWebHostBuilder ：Call UseLibuv on the IWebHostBuilder:

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

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

HTTP/1.1 要求清空HTTP/1.1 request draining

開啟 HTTP 連接相當耗時。Opening HTTP connections is time consuming. 若是 HTTPS，也需要大量資源。For HTTPS, it's also resource intensive. 因此，Kestrel 會嘗試針對每個 HTTP/1.1 通訊協定重複使用連接。Therefore, Kestrel tries to reuse connections per the HTTP/1.1 protocol. 要求主體必須完全取用，才能重複使用連線。A request body must be fully consumed to allow the connection to be reused. 應用程式不一定會取用要求主體，例如伺服器傳回重新 POST 導向或404回應的要求。The app doesn't always consume the request body, such as a POST requests where the server returns a redirect or 404 response. 在 POST -重新導向案例中：In the POST-redirect case:

用戶端可能已經傳送部分 POST 資料。The client may already have sent part of the POST data.
伺服器會寫入301回應。The server writes the 301 response.
連線無法用於新的要求，直到 POST 前一個要求主體的資料已完全讀取為止。The connection can't be used for a new request until the POST data from the previous request body has been fully read.
Kestrel 會嘗試清空要求主體。Kestrel tries to drain the request body. 清空要求主體表示在不處理資料的情況下讀取和捨棄資料。Draining the request body means reading and discarding the data without processing it.

清空程式可讓您在允許連線重複使用時，以及清空任何剩餘資料所需的時間之間進行 tradoff：The draining process makes a tradoff between allowing the connection to be reused and the time it takes to drain any remaining data:

清空有五秒的時間，無法設定。Draining has a timeout of five seconds, which isn't configurable.
如果或標頭所指定的所有資料在 Content-Length Transfer-Encoding 此時間之前未被讀取，則連接會關閉。If all of the data specified by the Content-Length or Transfer-Encoding header hasn't been read before the timeout, the connection is closed.

有時您可能會想要在寫入回應之前或之後立即終止要求。Sometimes you may want to terminate the request immediately, before or after writing the response. 例如，用戶端可能會有限制性的資料上限，因此限制上傳的資料可能是優先考慮。For example, clients may have restrictive data caps, so limiting uploaded data might be a priority. 在這種情況下，若要終止要求，請從控制器、頁面或中介軟體呼叫HttpCoNtext. Abort 。 RazorIn such cases to terminate a request, call HttpContext.Abort from a controller, Razor Page, or middleware.

呼叫時有一些注意事項 Abort ：There are caveats to calling Abort:

建立新的連接可能很慢且昂貴。Creating new connections can be slow and expensive.
在連接關閉之前，不保證用戶端已讀取回應。There's no guarantee that the client has read the response before the connection closes.
呼叫 Abort 應該很罕見，而且會保留給嚴重的錯誤案例，而不是常見的錯誤。Calling Abort should be rare and reserved for severe error cases, not common errors.
- 只有 Abort 在需要解決特定問題時才呼叫。Only call Abort when a specific problem needs to be solved. 例如， Abort 如果惡意用戶端嘗試 POST 資料或用戶端程式代碼中有錯誤，而導致大量或許多要求，請呼叫。For example, call Abort if malicious clients are trying to POST data or when there's a bug in client code that causes large or numerous requests.
- 請勿呼叫 Abort 常見的錯誤狀況，例如 HTTP 404 (找不到) 。Don't call Abort for common error situations, such as HTTP 404 (Not Found).

在呼叫之前呼叫 HttpResponse ， Abort 可確保伺服器已完成寫入回應。Calling HttpResponse.CompleteAsync before calling Abort ensures that the server has completed writing the response. 不過，用戶端行為不是可預測的，而且在中斷連接之前，可能不會讀取回應。However, client behavior isn't predictable and they may not read the response before the connection is aborted.

HTTP/2 的這個程式不同，因為通訊協定支援中止個別要求資料流程，而不需要關閉連接。This process is different for HTTP/2 because the protocol supports aborting individual request streams without closing the connection. 五秒的清空超時時間不適用。The five second drain timeout doesn't apply. 如果在完成回應之後有任何未讀取的要求主體資料，則伺服器會傳送 HTTP/2 RST 框架。If there's any unread request body data after completing a response, then the server sends an HTTP/2 RST frame. 系統會忽略其他要求主體資料框架。Additional request body data frames are ignored.

可能的話，最好是讓用戶端利用預期的： 100-continue 要求標頭，並等待伺服器回應，然後再開始傳送要求本文。If possible, it's better for clients to utilize the Expect: 100-continue request header and wait for the server to respond before starting to send the request body. 這可讓用戶端有機會檢查回應，並在傳送不需要的資料之前中止。That gives the client an opportunity to examine the response and abort before sending unneeded data.

其他資源Additional resources

在 Linux 上使用 UNIX 通訊端時，通訊端不會在應用程式關閉時自動刪除。When using UNIX sockets on Linux, the socket is not automatically deleted on app shut down. 如需詳細資訊，請參閱此 GitHub 問題。For more information, see this GitHub issue.
針對 ASP.NET Core 專案進行疑難排解和調試
在 ASP.NET Core 中強制使用 HTTPS
設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作
RFC 7230：訊息語法和路由 (第 5.4 節：主機)RFC 7230: Message Syntax and Routing (Section 5.4: Host)

Kestrel 支援下列案例：Kestrel supports the following scenarios:

HTTPSHTTPS
用來啟用 WebSockets 的不透明升級Opaque upgrade used to enable WebSockets
Nginx 背後的高效能 Unix 通訊端Unix sockets for high performance behind Nginx
HTTP/2 (macOS 上除外†)HTTP/2 (except on macOS†)

†未來版本的 macOS 上將會支援 HTTP/2。†HTTP/2 will be supported on macOS in a future release.

.NET Core 支援的所有平台和版本都支援 Kestrel。Kestrel is supported on all platforms and versions that .NET Core supports.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

HTTP/2 支援HTTP/2 support

如果符合下列基本需求，則可以針對 ASP.NET Core 應用程式使用 HTTP/2：HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

作業系統†Operating system†
- Windows Server 2016/Windows 10 或更新版本‡Windows Server 2016/Windows 10 or later‡
- Linux 含 OpenSSL 1.0.2 或更新版本 (例如 Ubuntu 16.04 或更新版本)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
目標 Framework：.NET Core 2.2 或更新版本Target framework: .NET Core 2.2 or later
Application-Layer Protocol Negotiation (ALPN) 連線Application-Layer Protocol Negotiation (ALPN) connection
TLS 1.2 或更新版本連線TLS 1.2 or later connection

如果已建立 HTTP/2 連線，HttpRequest.Protocol 會報告 HTTP/2。If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

預設會停用 HTTP/2。HTTP/2 is disabled by default. 如需組態的詳細資訊，請參閱 Kestrel 選項和 ListenOptions. 通訊協定一節。For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

何時搭配使用 Kestrel 與反向 ProxyWhen to use Kestrel with a reverse proxy

Kestrel 用作邊緣 (網際網路對應) 網頁伺服器：Kestrel used as an edge (Internet-facing) web server:

Kestrel 不使用反向 Proxy 伺服器直接與網際網路通訊

Kestrel 用於反向 Proxy 組態中：Kestrel used in a reverse proxy configuration:

Kestrel 透過 IIS、Nginx 或 Apache 等反向 Proxy 伺服器間接與網際網路通訊

不論是否有反向 proxy 伺服器，設定都是支援的裝載設定。Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

即使不需要反向 Proxy 伺服器，使用反向 Proxy 伺服器也是不錯的選擇。Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

反向 Proxy：A reverse proxy:

可以限制它所主控之應用程式的公開介面區。Can limit the exposed public surface area of the apps that it hosts.
提供額外的組態和防禦層。Provide an additional layer of configuration and defense.
能夠與現有基礎結構更好地整合。Might integrate better with existing infrastructure.
簡化負載平衡和安全通訊 (HTTPS) 組態。Simplify load balancing and secure communication (HTTPS) configuration. 只有反向 proxy 伺服器需要 x.509 憑證，而且該伺服器可以使用一般 HTTP 與內部網路上的應用程式伺服器進行通訊。Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.

如何在 ASP.NET Core 應用程式中使用 KestrelHow to use Kestrel in ASP.NET Core apps

AspNetCore 會包含在AspNetCore.. 中繼套件. Kestrel套件中。The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

ASP.NET Core 專案範本預設會使用 Kestrel。ASP.NET Core project templates use Kestrel by default. 在 Program.cs 中，範本程式碼會呼叫 CreateDefaultBuilder，而後者會在幕後呼叫 UseKestrel。In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

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

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

如需 CreateDefaultBuilder 和建立主機的詳細資訊，請參閱的 設定主機 一節 ASP.NET Core Web 主機。For more information on CreateDefaultBuilder and building the host, see the Set up a host section of ASP.NET Core Web 主機.

若要在呼叫 CreateDefaultBuilder 之後提供額外的設定，請使用 ConfigureKestrel：To provide additional configuration after calling CreateDefaultBuilder, use ConfigureKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        });

如果應用程式未呼叫 CreateDefaultBuilder 來設定主機，請在呼叫 ConfigureKestrel 之前，先呼叫 UseKestrel：If the app doesn't call CreateDefaultBuilder to set up the host, call UseKestrel before calling ConfigureKestrel:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        })
        .Build();

    host.Run();
}

Kestrel 選項Kestrel options

下列範例會使用 Microsoft.AspNetCore.Server.Kestrel.Core 命名空間；The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

您也可以使用設定提供者來設定 Kestrel 選項（在下列範例中以 c # 程式碼設定）。Kestrel options, which are configured in C# code in the following examples, can also be set using a configuration provider. 例如，檔案設定提供者可以從或 appsettings 載入 Kestrel 設定 appsettings.json 。環境}. json 檔案：For example, the File Configuration Provider can load Kestrel configuration from an appsettings.json or appsettings.{Environment}.json file:

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

使用下列 其中一 種方法：Use one of the following approaches:

設定 Kestrel in Startup.ConfigureServices ：Configure Kestrel in Startup.ConfigureServices:
1. 將的實例插入 IConfiguration 至 Startup 類別。Inject an instance of IConfiguration into the Startup class. 下列範例假設將插入的設定指派給 Configuration 屬性。The following example assumes that the injected configuration is assigned to the Configuration property.
2. 在中 Startup.ConfigureServices ，將 Kestrel configuration 區段載入 Kestrel 的設定：In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:
```
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)
    {
        ...
    }
}
```

設定 Kestrel 建立主機時：Configure Kestrel when building the host:

在 Program.cs 中，將 Kestrel Configuration 區段載入 Kestrel 的設定中：In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

// using Microsoft.Extensions.DependencyInjection;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.Configure<KestrelServerOptions>(
                context.Configuration.GetSection("Kestrel"));
        })
        .UseStartup<Startup>();

上述兩種方法都可搭配任何設定提供者使用。Both of the preceding approaches work with any configuration provider.

Keep-alive 逾時Keep-alive timeout

KeepAliveTimeout

取得或設定 Keep-alive 逾時 (英文)。Gets or sets the keep-alive timeout. 預設為 2 分鐘。Defaults to 2 minutes.

.ConfigureKestrel((context, 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);
});

用戶端連線數目上限Maximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

.ConfigureKestrel((context, 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);
});

.ConfigureKestrel((context, 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);
});

連線數目上限預設為無限制 (null)。The maximum number of connections is unlimited (null) by default.

要求主體大小上限Maximum request body size

MaxRequestBodySize

預設的要求主體大小上限是 30,000,000 個位元組，大約 28.6 MB。The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

以下範例會示範如何設定應用程式、每個要求的條件約束：Here's an example that shows how to configure the constraint for the app on every request:

.ConfigureKestrel((context, 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);
});

覆寫中介軟體中特定要求的設定：Override the setting on a specific request in 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));
    }

要求主體資料速率下限Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

預設速率下限為 240 個位元組/秒，寬限期為 5 秒。The default minimum rate is 240 bytes/second with a 5 second grace period.

以下範例示範如何在 Program.cs 中設定資料速率下限：Here's an example that shows how to configure the minimum data rates in Program.cs:

.ConfigureKestrel((context, 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);
});

覆寫中介軟體中每個要求的最小速率限制：Override the minimum rate limits per request in 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));
    }

因為通訊協定對要求多工的支援，所以 HTTP/2 不支援以每一要求基礎修改速率限制，進而使先前範例中所參考的所有速率功能都不會出現在 HTTP/2 要求的 HttpContext.Features 中。Neither rate feature referenced in the prior sample are present in HttpContext.Features for HTTP/2 requests because modifying rate limits on a per-request basis isn't supported for HTTP/2 due to the protocol's support for request multiplexing. 透過 KestrelServerOptions.Limits 設定的全伺服器速率限制皆仍套用至 HTTP/1.x 及 HTTP/2 連線。Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

要求標頭逾時Request headers timeout

RequestHeadersTimeout

取得或設定伺服器花費在接收要求標頭的時間上限。Gets or sets the maximum amount of time the server spends receiving request headers. 預設為 30 秒。Defaults to 30 seconds.

.ConfigureKestrel((context, 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);
});

每個連線的資料流數目上限Maximum streams per connection

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxStreamsPerConnection = 100;
        });

預設值是 100。The default value is 100.

標頭表格大小Header table size

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.HeaderTableSize = 4096;
        });

預設值為 4096。The default value is 4096.

框架大小上限Maximum frame size

Http2.MaxFrameSize 表示要接收的 HTTP/2 連線框架承載大小上限。Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. 這個值是以八位元提供，而且必須介於 2^14 (16,384) 到 2^24-1 (16,777,215) 之間。The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxFrameSize = 16384;
        });

預設值為 2^14 (16,384)。The default value is 2^14 (16,384).

要求標頭大小上限Maximum request header size

Http2.MaxRequestHeaderFieldSize 以八位元表示要求標頭值的允許大小上限。Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. 此限制皆共同套用至已壓縮及未壓縮代表中的名稱與值。This limit applies to both name and value together in their compressed and uncompressed representations. 此值必須大於零 (0)。The value must be greater than zero (0).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.MaxRequestHeaderFieldSize = 8192;
        });

預設值為 8,192。The default value is 8,192.

初始連線視窗大小Initial connection window size

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialConnectionWindowSize = 131072;
        });

預設值為 128 KB (131,072)。The default value is 128 KB (131,072).

初始資料流視窗大小Initial stream window size

Http2.InitialStreamWindowSize 會以位元組表示每個要求 (資料流) 單次伺服器緩衝的要求內容資料上限。Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). 要求也皆受 Http2.InitialStreamWindowSize 所限制。Requests are also limited by Http2.InitialStreamWindowSize. 此值必須大於或等於 65,535，且小於 2^31 (2,147,483,648)。The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Limits.Http2.InitialStreamWindowSize = 98304;
        });

預設值為 96 KB (98,304)。The default value is 96 KB (98,304).

同步 I/OSynchronous I/O

AllowSynchronousIO 控制要求和回應是否允許同步 i/o。AllowSynchronousIO controls whether synchronous I/O is allowed for the request and response. 預設值為 true。The default value is true.

警告

下列範例會啟用同步 i/o：The following example enables synchronous I/O:

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

如需其他 Kestrel 選項和限制的資訊，請參閱：For information about other Kestrel options and limits, see:

端點組態Endpoint configuration

ASP.NET Core 預設會繫結至：By default, ASP.NET Core binds to:

http://localhost:5000
https://localhost:5001 (當有本機開發憑證存在時)https://localhost:5001 (when a local development certificate is present)

使用以下各項指定 URL：Specify URLs using the:

ASPNETCORE_URLS 環境變數。ASPNETCORE_URLS environment variable.
--urls 命令列引數。--urls command-line argument.
urls 主機組態索引鍵。urls host configuration key.
UseUrls 擴充方法。UseUrls extension method.

如需有關這些方法的詳細資訊，請參閱伺服器 URL 和覆寫設定。For more information on these approaches, see Server URLs and Override configuration.

開發憑證會建立於：A development certificate is created:

已安裝 .NET Core SDK 時。When the .NET Core SDK is installed.
dev-certs 工具用來建立憑證。The dev-certs tool is used to create a certificate.

某些瀏覽器需要授與明確的許可權，以信任本機開發憑證。Some browsers require granting explicit permission to trust the local development certificate.

KestrelServerOptions 配置：KestrelServerOptions configuration:

ConfigureEndpointDefaults (動作 <ListenOptions>) ConfigureEndpointDefaults(Action<ListenOptions>)

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

注意

ConfigureHttpsDefaults (動作 <HttpsConnectionAdapterOptions>) ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

注意

Configure(IConfiguration)Configure(IConfiguration)

ListenOptions.UseHttpsListenOptions.UseHttps

設定 Kestrel 使用 HTTPS。Configure Kestrel to use HTTPS.

ListenOptions.UseHttps 延伸模組：ListenOptions.UseHttps extensions:

UseHttps：設定 Kestrel 以搭配預設憑證使用 HTTPS。UseHttps: Configure Kestrel to use HTTPS with the default certificate. 如果未設定預設憑證，會擲回例外狀況。Throws an exception if no default certificate is configured.
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 參數：ListenOptions.UseHttps parameters:

filename 是憑證檔案的路徑和檔案名稱，它相對於包含應用程式內容檔案的目錄。filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
password 是存取 X.509 憑證資料所需的密碼。password is the password required to access the X.509 certificate data.
configureOptions 是設定 HttpsConnectionAdapterOptions 的 Action。configureOptions is an Action to configure the HttpsConnectionAdapterOptions. 傳回 ListenOptions。Returns the ListenOptions.
storeName 是要從中載入憑證的憑證存放區。storeName is the certificate store from which to load the certificate.
subject 是憑證的主體名稱。subject is the subject name for the certificate.
allowInvalid 表示是否應該考慮無效的憑證，例如自我簽署憑證。allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
location 是要從中載入憑證的存放區位置。location is the store location to load the certificate from.
serverCertificate 是 X.509 憑證。serverCertificate is the X.509 certificate.

在生產環境中，必須明確設定 HTTPS。In production, HTTPS must be explicitly configured. 至少必須提供預設憑證。At a minimum, a default certificate must be provided.

支援的組態描述如下：Supported configurations described next:

無組態No configuration
從組態取代預設憑證Replace the default certificate from configuration
變更程式碼中的預設值Change the defaults in code

無組態No configuration

從組態取代預設憑證Replace the default certificate from configuration

在下列 appsettings.json 範例中：In the following appsettings.json example:

將 AllowInvalid 設定為 true，允許使用無效的憑證 (例如，自我簽署憑證)。Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
任何未指定憑證 (接下來範例中的 HttpsDefaultCert) 的 HTTPS 端點會回復為 [憑證][預設] > 下定義的憑證或開發憑證。Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.

{
  "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>"
      }
    }
  }
}

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

結構描述附註：Schema notes:

端點名稱不區分大小寫。Endpoints names are case-insensitive. 例如，HTTPS 和 Https 都有效。For example, HTTPS and Https are valid.
Url 參數對每個端點而言都是必要的。The Url parameter is required for each endpoint. 此參數的格式等同於最上層 Urls 組態參數，但是它限制為單一值。The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
這些端點會取代最上層 Urls 組態中定義的端點，而不是新增至其中。These endpoints replace those defined in the top-level Urls configuration rather than adding to them. 透過 Listen 在程式碼中定義的端點，會與組態區段中定義的端點累計。Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
Certificate 區段是選擇性的。The Certificate section is optional. 如果未指定 Certificate 區段，則會使用先前案例中所定義的預設值。If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. 如果沒有預設值可供使用，伺服器就會擲回例外狀況，且無法啟動。If no defaults are available, the server throws an exception and fails to start.
Certificate區段同時支援路徑 – 密碼和主體 – 存放區 憑證。The Certificate section supports both Path–Password and Subject–Store certificates.
可以用這種方式定義任何數目的端點，只要它們不會導致連接埠衝突即可。Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
options.Configure(context.Configuration.GetSection("{SECTION}")) 會傳回 KestrelConfigurationLoader 與 .Endpoint(string name, listenOptions => { }) 方法，此方法可用來補充已設定的端點設定：options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

您可以在方法的選項中使用每個端點的設定區段， Endpoint 以便讀取自訂設定。The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
可以藉由使用另一個區段再次呼叫 options.Configure(context.Configuration.GetSection("{SECTION}")) 而載入多個組態。Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. 只會使用最後一個組態，除非在先前的執行個體上已明確呼叫 Load。Only the last configuration is used, unless Load is explicitly called on prior instances. 中繼套件不會呼叫 Load，如此可能會取代其預設組態區段。The metapackage doesn't call Load so that its default configuration section may be replaced.
KestrelConfigurationLoader 會將來自 KestrelServerOptions 的 API 的 Listen 系列鏡像為 Endpoint 多載，所以可在相同的位置設定程式碼和設定端點。KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. 這些多載不使用名稱，並且只使用來自組態的預設組態。These overloads don't use names and only consume default settings from configuration.

變更程式碼中的預設值Change the defaults in code

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

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

SNI 的 Kestrel 支援Kestrel support for SNI

SNI 支援需要：SNI support requires:

在目標 framework netcoreapp2.1 或更新版本上執行。Running on target framework netcoreapp2.1 or later. 在 net461 或更新版本中，會叫用回呼，但 name 一律為 null 。On net461 or later, the callback is invoked but the name is always null. 如果用戶端不在 TLS 信號交換中提供主機名稱參數，則 name 也是 null。The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
所有網站都在相同的 Kestrel 執行個體上執行。All websites run on the same Kestrel instance. 在不使用反向 Proxy 的情況下，Kestrel 不支援跨多個執行個體共用 IP 位址和連接埠。Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, 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;
                    };
                });
            });
        });

連接記錄Connection logging

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

繫結至 TCP 通訊端Bind to a TCP socket

Listen 方法會繫結至 TCP 通訊端，而選項 Lambda 則會允許 X.509 憑證設定：The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

在 macOS、Linux 和 Windows 上，可以使用 OpenSSL (英文) 建立憑證。On macOS, Linux, and Windows, certificates can be created using OpenSSL.

繫結至 Unix 通訊端Bind to a Unix socket

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testpassword");
    });
});

在 Nginx confiuguration 檔案中，將 server > location > proxy_pass 專案設定為 http://unix:/tmp/{KESTREL SOCKET}:/; 。In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} 這是提供給 (的通訊端名稱 ListenUnixSocket ，例如 kestrel-test.sock 上述範例) 。{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
確定 Nginx (可寫入通訊端，例如 chmod go+w /tmp/kestrel-test.sock) 。Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

連接埠 0Port 0

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

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

限制Limitations

使用下列方法來設定端點：Configure endpoints with the following approaches:

UseUrls
--urls 命令列引數--urls command-line argument
urls 主機組態索引鍵urls host configuration key
ASPNETCORE_URLS 環境變數ASPNETCORE_URLS environment variable

HTTPS 無法與這些方法搭配使用，除非在 HTTPS 端點設定中提供預設憑證 (例如，使用 KestrelServerOptions 設定或設定檔，如本主題稍早所示)。HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
當同時使用 Listen 和 UseUrls 方法時，Listen 端點會覆寫 UseUrls 端點。When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS 端點設定IIS endpoint configuration

ListenOptions.ProtocolsListenOptions.Protocols

`HttpProtocols` 列舉值`HttpProtocols` enum value	允許的連線通訊協定Connection protocol permitted
`Http1`	僅限 HTTP/1.1。HTTP/1.1 only. 可在具有或沒有 TLS 的情況下使用。Can be used with or without TLS.
`Http2`	僅限 HTTP/2。HTTP/2 only. 只有在用戶端支援先備知識模式時，才可以在沒有 TLS 的情況下使用。May be used without TLS only if the client supports a Prior Knowledge mode.
`Http1AndHttp2`	HTTP/1.1 和 HTTP/2。HTTP/1.1 and HTTP/2. HTTP/2 需要 TLS 和應用層通訊協定協商 (ALPN) 連接;否則，連接預設為 HTTP/1.1。HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

預設通訊協定為 HTTP/1.1。The default protocol is HTTP/1.1.

HTTP/2 的 TLS 限制：TLS restrictions for HTTP/2:

TLS 1.2 版或更新版本TLS version 1.2 or later
已停用重新交涉Renegotiation disabled
已停用壓縮Compression disabled
暫時金鑰交換大小下限：Minimum ephemeral key exchange sizes:
- 橢圓曲線 Diffie-Hellman (>ECDHE) [ RFC4492 ] ：最少224位Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: 224 bits minimum
- 有限的欄位 Diffie-Hellman (DHE) [ TLS12 ] ：最低2048位Finite field Diffie-Hellman (DHE) [TLS12]: 2048 bits minimum
未封鎖加密套件Cipher suite not blocked

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

選擇性地建立 IConnectionAdapter 實作，針對每個連線來篩選特定加密的 TLS 交握：Optionally create an IConnectionAdapter implementation to filter TLS handshakes on a per-connection basis for specific ciphers:

.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.ConnectionAdapters.Add(new TlsFilterAdapter());
    });
});

private class TlsFilterAdapter : IConnectionAdapter
{
    public bool IsHttps => false;

    public Task<IAdaptedConnection> OnConnectionAsync(ConnectionAdapterContext context)
    {
        var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

        // Throw NotSupportedException for any cipher algorithm that the app doesn't
        // wish to support. Alternatively, define and compare
        // ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
        // suites.
        //
        // No encryption is used with a CipherAlgorithmType.Null cipher algorithm.
        if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
        {
            throw new NotSupportedException("Prohibited cipher: " + tlsFeature.CipherAlgorithm);
        }

        return Task.FromResult<IAdaptedConnection>(new AdaptedConnection(context.ConnectionStream));
    }

    private class AdaptedConnection : IAdaptedConnection
    {
        public AdaptedConnection(Stream adaptedStream)
        {
            ConnectionStream = adaptedStream;
        }

        public Stream ConnectionStream { get; }

        public void Dispose()
        {
        }
    }
}

從設定進行通訊協定設定Set the protocol from configuration

CreateDefaultBuilder 預設會呼叫 serverOptions.Configure(context.Configuration.GetSection("Kestrel")) 以載入 Kestrel 設定。CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

在下列 appsettings.json 範例中，會為 Kestrel 的所有端點建立預設的連接通訊協定， (HTTP/1.1 和 HTTP/2) ：In the following appsettings.json example, a default connection protocol (HTTP/1.1 and HTTP/2) is established for all of Kestrel's endpoints:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

下列設定檔範例會為特定端點建立連線通訊協定：The following configuration file example establishes a connection protocol for a specific endpoint:

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

程式碼中指定的通訊協定會覆寫設定所設定的值。Protocols specified in code override values set by configuration.

Libuv 傳輸設定Libuv transport configuration

隨著 ASP.NET Core 2.1 的發行，Kestrel 的預設傳輸不再根據 Libuv，而是改為根據受控通訊端。With the release of ASP.NET Core 2.1, Kestrel's default transport is no longer based on Libuv but instead based on managed sockets. 對於升級到 2.1 且會呼叫 UseLibuv 並相依於下列任一套件的 ASP.NET Core 2.0 應用程式來說，這是一項中斷性變更：This is a breaking change for ASP.NET Core 2.0 apps upgrading to 2.1 that call UseLibuv and depend on either of the following packages:

Microsoft.AspNetCore.Server.Kestrel (直接套件參考)Microsoft.AspNetCore.Server.Kestrel (direct package reference)
Microsoft.AspNetCore.AppMicrosoft.AspNetCore.App

針對需要使用 Libuv 的專案：For projects that require the use of Libuv:

將 Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv 套件的相依性新增至應用程式的專案檔中：Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:
```
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />
```

呼叫 UseLibuv：Call UseLibuv:

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

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

URL 前置詞URL prefixes

IPv4 位址與連接埠號碼IPv4 address with port number
```
http://65.55.39.10:80/
```
0.0.0.0 是繫結至所有 IPv4 位址的特殊情況。0.0.0.0 is a special case that binds to all IPv4 addresses.
IPv6 位址與連接埠號碼IPv6 address with port number
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] 是相當於 IPv4 0.0.0.0 的 IPv6 對等項目。[::] is the IPv6 equivalent of IPv4 0.0.0.0.
主機名稱與連接埠號碼Host name with port number
```
http://contoso.com:80/
http://*:80/
```
主機名稱 * 和 + 並不特殊。Host names, *, and +, aren't special. 無法辨識為有效 IP 位址或 localhost 的任何項目，都會繫結至所有 IPv4 和 IPv6 IP。Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. 若要在相同連接埠上將不同的主機名稱繫結至不同的 ASP.NET Core 應用程式，請使用 HTTP.sys 或反向 Proxy 伺服器 (例如 IIS、Nginx 或 Apache)。To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.
主機 localhost 名稱與連接埠號碼，或回送 IP 與連接埠號碼Host localhost name with port number or loopback IP with port number
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
如果指定 localhost，Kestrel 會嘗試同時繫結至 IPv4 和 IPv6 回送介面。When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. 如果所要求的連接埠在任一個回送介面上由另一個服務使用，則 Kestrel 無法啟動。If the requested port is in use by another service on either loopback interface, Kestrel fails to start. 如果任一回送介面由於任何其他原因 (最常見的原因是不支援 IPv6) 無法使用，Kestrel 就會記錄警告。If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

主機篩選Host filtering

因應措施是使用主機篩選中介軟體。As a workaround, use Host Filtering Middleware. 主機篩選中介軟體是由 AspNetCore HostFiltering 套件所提供，此套件隨附于 AspNetCore 中繼套件 (ASP.NET Core 2.1 或 2.2) 。Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or 2.2). 中介軟體是由 CreateDefaultBuilder 所新增，它會呼叫 AddHostFiltering：The middleware is added by CreateDefaultBuilder, which calls 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>();
}

appsettings.json:appsettings.json:

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

注意

HTTP/1.1 要求清空HTTP/1.1 request draining

用戶端可能已經傳送部分 POST 資料。The client may already have sent part of the POST data.
伺服器會寫入301回應。The server writes the 301 response.
連線無法用於新的要求，直到 POST 前一個要求主體的資料已完全讀取為止。The connection can't be used for a new request until the POST data from the previous request body has been fully read.
Kestrel 會嘗試清空要求主體。Kestrel tries to drain the request body. 清空要求主體表示在不處理資料的情況下讀取和捨棄資料。Draining the request body means reading and discarding the data without processing it.

清空有五秒的時間，無法設定。Draining has a timeout of five seconds, which isn't configurable.
如果或標頭所指定的所有資料在 Content-Length Transfer-Encoding 此時間之前未被讀取，則連接會關閉。If all of the data specified by the Content-Length or Transfer-Encoding header hasn't been read before the timeout, the connection is closed.

呼叫時有一些注意事項 Abort ：There are caveats to calling Abort:

建立新的連接可能很慢且昂貴。Creating new connections can be slow and expensive.
在連接關閉之前，不保證用戶端已讀取回應。There's no guarantee that the client has read the response before the connection closes.
呼叫 Abort 應該很罕見，而且會保留給嚴重的錯誤案例，而不是常見的錯誤。Calling Abort should be rare and reserved for severe error cases, not common errors.
- 只有 Abort 在需要解決特定問題時才呼叫。Only call Abort when a specific problem needs to be solved. 例如， Abort 如果惡意用戶端嘗試 POST 資料或用戶端程式代碼中有錯誤，而導致大量或許多要求，請呼叫。For example, call Abort if malicious clients are trying to POST data or when there's a bug in client code that causes large or numerous requests.
- 請勿呼叫 Abort 常見的錯誤狀況，例如 HTTP 404 (找不到) 。Don't call Abort for common error situations, such as HTTP 404 (Not Found).

其他資源Additional resources

在 Linux 上使用 UNIX 通訊端時，通訊端不會在應用程式關閉時自動刪除。When using UNIX sockets on Linux, the socket is not automatically deleted on app shut down. 如需詳細資訊，請參閱此 GitHub 問題。For more information, see this GitHub issue.
針對 ASP.NET Core 專案進行疑難排解和調試
在 ASP.NET Core 中強制使用 HTTPS
設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作
RFC 7230：訊息語法和路由 (第 5.4 節：主機)RFC 7230: Message Syntax and Routing (Section 5.4: Host)

Kestrel 支援下列案例：Kestrel supports the following scenarios:

HTTPSHTTPS
用來啟用 WebSockets 的不透明升級Opaque upgrade used to enable WebSockets
Nginx 背後的高效能 Unix 通訊端Unix sockets for high performance behind Nginx

.NET Core 支援的所有平台和版本都支援 Kestrel。Kestrel is supported on all platforms and versions that .NET Core supports.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

何時搭配使用 Kestrel 與反向 ProxyWhen to use Kestrel with a reverse proxy

Kestrel 用作邊緣 (網際網路對應) 網頁伺服器：Kestrel used as an edge (Internet-facing) web server:

Kestrel 不使用反向 Proxy 伺服器直接與網際網路通訊

Kestrel 用於反向 Proxy 組態中：Kestrel used in a reverse proxy configuration:

Kestrel 透過 IIS、Nginx 或 Apache 等反向 Proxy 伺服器間接與網際網路通訊

不論是否有反向 proxy 伺服器，設定都是支援的裝載設定。Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

即使不需要反向 Proxy 伺服器，使用反向 Proxy 伺服器也是不錯的選擇。Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

反向 Proxy：A reverse proxy:

可以限制它所主控之應用程式的公開介面區。Can limit the exposed public surface area of the apps that it hosts.
提供額外的組態和防禦層。Provide an additional layer of configuration and defense.
能夠與現有基礎結構更好地整合。Might integrate better with existing infrastructure.
簡化負載平衡和安全通訊 (HTTPS) 組態。Simplify load balancing and secure communication (HTTPS) configuration. 只有反向 proxy 伺服器需要 x.509 憑證，而且該伺服器可以使用一般 HTTP 與內部網路上的應用程式伺服器進行通訊。Only the reverse proxy server requires an X.509 certificate, and that server can communicate with the app's servers on the internal network using plain HTTP.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.

如何在 ASP.NET Core 應用程式中使用 KestrelHow to use Kestrel in ASP.NET Core apps

AspNetCore 會包含在AspNetCore.. 中繼套件. Kestrel套件中。The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

若要在呼叫 CreateDefaultBuilder 之後提供額外的設定，請呼叫 UseKestrel：To provide additional configuration after calling CreateDefaultBuilder, call UseKestrel:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            // Set properties and call methods on serverOptions
        });

Kestrel 選項Kestrel options

下列範例會使用 Microsoft.AspNetCore.Server.Kestrel.Core 命名空間；The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

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

使用下列 其中一 種方法：Use one of the following approaches:

設定 Kestrel in Startup.ConfigureServices ：Configure Kestrel in Startup.ConfigureServices:
1. 將的實例插入 IConfiguration 至 Startup 類別。Inject an instance of IConfiguration into the Startup class. 下列範例假設將插入的設定指派給 Configuration 屬性。The following example assumes that the injected configuration is assigned to the Configuration property.
2. 在中 Startup.ConfigureServices ，將 Kestrel configuration 區段載入 Kestrel 的設定：In Startup.ConfigureServices, load the Kestrel section of configuration into Kestrel's configuration:
```
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)
    {
        ...
    }
}
```

設定 Kestrel 建立主機時：Configure Kestrel when building the host:

在 Program.cs 中，將 Kestrel Configuration 區段載入 Kestrel 的設定中：In Program.cs, load the Kestrel section of configuration into Kestrel's configuration:

// using Microsoft.Extensions.DependencyInjection;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.Configure<KestrelServerOptions>(
                context.Configuration.GetSection("Kestrel"));
        })
        .UseStartup<Startup>();

上述兩種方法都可搭配任何設定提供者使用。Both of the preceding approaches work with any configuration provider.

Keep-alive 逾時Keep-alive timeout

KeepAliveTimeout

取得或設定 Keep-alive 逾時 (英文)。Gets or sets the keep-alive timeout. 預設為 2 分鐘。Defaults to 2 minutes.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.KeepAliveTimeout = TimeSpan.FromMinutes(2);
        });

用戶端連線數目上限Maximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentConnections = 100;
        });

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxConcurrentUpgradedConnections = 100;
        });

連線數目上限預設為無限制 (null)。The maximum number of connections is unlimited (null) by default.

要求主體大小上限Maximum request body size

MaxRequestBodySize

預設的要求主體大小上限是 30,000,000 個位元組，大約 28.6 MB。The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

[RequestSizeLimit(100000000)]
public IActionResult MyActionMethod()

以下範例會示範如何設定應用程式、每個要求的條件約束：Here's an example that shows how to configure the constraint for the app on every request:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MaxRequestBodySize = 10 * 1024;
        });

覆寫中介軟體中特定要求的設定：Override the setting on a specific request in 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));
    }

要求主體資料速率下限Minimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

預設速率下限為 240 個位元組/秒，寬限期為 5 秒。The default minimum rate is 240 bytes/second with a 5 second grace period.

以下範例示範如何在 Program.cs 中設定資料速率下限：Here's an example that shows how to configure the minimum data rates in Program.cs:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.MinRequestBodyDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
            serverOptions.Limits.MinResponseDataRate =
                new MinDataRate(bytesPerSecond: 100, gracePeriod: TimeSpan.FromSeconds(10));
        });

要求標頭逾時Request headers timeout

RequestHeadersTimeout

取得或設定伺服器花費在接收要求標頭的時間上限。Gets or sets the maximum amount of time the server spends receiving request headers. 預設為 30 秒。Defaults to 30 seconds.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Limits.RequestHeadersTimeout = TimeSpan.FromMinutes(1);
        });

同步 I/OSynchronous I/O

警告

下列範例會停用同步 i/o：The following example disables synchronous I/O:

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

如需其他 Kestrel 選項和限制的資訊，請參閱：For information about other Kestrel options and limits, see:

端點組態Endpoint configuration

ASP.NET Core 預設會繫結至：By default, ASP.NET Core binds to:

http://localhost:5000
https://localhost:5001 (當有本機開發憑證存在時)https://localhost:5001 (when a local development certificate is present)

使用以下各項指定 URL：Specify URLs using the:

ASPNETCORE_URLS 環境變數。ASPNETCORE_URLS environment variable.
--urls 命令列引數。--urls command-line argument.
urls 主機組態索引鍵。urls host configuration key.
UseUrls 擴充方法。UseUrls extension method.

如需有關這些方法的詳細資訊，請參閱伺服器 URL 和覆寫設定。For more information on these approaches, see Server URLs and Override configuration.

開發憑證會建立於：A development certificate is created:

已安裝 .NET Core SDK 時。When the .NET Core SDK is installed.
dev-certs 工具用來建立憑證。The dev-certs tool is used to create a certificate.

某些瀏覽器需要授與明確的許可權，以信任本機開發憑證。Some browsers require granting explicit permission to trust the local development certificate.

KestrelServerOptions 配置：KestrelServerOptions configuration:

ConfigureEndpointDefaults (動作 <ListenOptions>) ConfigureEndpointDefaults(Action<ListenOptions>)

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });
        });

注意

ConfigureHttpsDefaults (動作 <HttpsConnectionAdapterOptions>) ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureHttpsDefaults(listenOptions =>
            {
                // certificate is an X509Certificate2
                listenOptions.ServerCertificate = certificate;
            });
        });

注意

Configure(IConfiguration)Configure(IConfiguration)

ListenOptions.UseHttpsListenOptions.UseHttps

設定 Kestrel 使用 HTTPS。Configure Kestrel to use HTTPS.

ListenOptions.UseHttps 延伸模組：ListenOptions.UseHttps extensions:

UseHttps：設定 Kestrel 以搭配預設憑證使用 HTTPS。UseHttps: Configure Kestrel to use HTTPS with the default certificate. 如果未設定預設憑證，會擲回例外狀況。Throws an exception if no default certificate is configured.
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 參數：ListenOptions.UseHttps parameters:

filename 是憑證檔案的路徑和檔案名稱，它相對於包含應用程式內容檔案的目錄。filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
password 是存取 X.509 憑證資料所需的密碼。password is the password required to access the X.509 certificate data.
configureOptions 是設定 HttpsConnectionAdapterOptions 的 Action。configureOptions is an Action to configure the HttpsConnectionAdapterOptions. 傳回 ListenOptions。Returns the ListenOptions.
storeName 是要從中載入憑證的憑證存放區。storeName is the certificate store from which to load the certificate.
subject 是憑證的主體名稱。subject is the subject name for the certificate.
allowInvalid 表示是否應該考慮無效的憑證，例如自我簽署憑證。allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
location 是要從中載入憑證的存放區位置。location is the store location to load the certificate from.
serverCertificate 是 X.509 憑證。serverCertificate is the X.509 certificate.

在生產環境中，必須明確設定 HTTPS。In production, HTTPS must be explicitly configured. 至少必須提供預設憑證。At a minimum, a default certificate must be provided.

支援的組態描述如下：Supported configurations described next:

無組態No configuration
從組態取代預設憑證Replace the default certificate from configuration
變更程式碼中的預設值Change the defaults in code

無組態No configuration

從組態取代預設憑證Replace the default certificate from configuration

在下列 appsettings.json 範例中：In the following appsettings.json example:

將 AllowInvalid 設定為 true，允許使用無效的憑證 (例如，自我簽署憑證)。Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
任何未指定憑證 (接下來範例中的 HttpsDefaultCert) 的 HTTPS 端點會回復為 [憑證][預設] > 下定義的憑證或開發憑證。Any HTTPS endpoint that doesn't specify a certificate (HttpsDefaultCert in the example that follows) falls back to the cert defined under Certificates > Default or the development certificate.

{
  "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>"
      }
    }
  }
}

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

結構描述附註：Schema notes:

端點名稱不區分大小寫。Endpoints names are case-insensitive. 例如，HTTPS 和 Https 都有效。For example, HTTPS and Https are valid.
Url 參數對每個端點而言都是必要的。The Url parameter is required for each endpoint. 此參數的格式等同於最上層 Urls 組態參數，但是它限制為單一值。The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
這些端點會取代最上層 Urls 組態中定義的端點，而不是新增至其中。These endpoints replace those defined in the top-level Urls configuration rather than adding to them. 透過 Listen 在程式碼中定義的端點，會與組態區段中定義的端點累計。Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
Certificate 區段是選擇性的。The Certificate section is optional. 如果未指定 Certificate 區段，則會使用先前案例中所定義的預設值。If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. 如果沒有預設值可供使用，伺服器就會擲回例外狀況，且無法啟動。If no defaults are available, the server throws an exception and fails to start.
Certificate區段同時支援路徑 – 密碼和主體 – 存放區 憑證。The Certificate section supports both Path–Password and Subject–Store certificates.
可以用這種方式定義任何數目的端點，只要它們不會導致連接埠衝突即可。Any number of endpoints may be defined in this way so long as they don't cause port conflicts.
options.Configure(context.Configuration.GetSection("{SECTION}")) 會傳回 KestrelConfigurationLoader 與 .Endpoint(string name, listenOptions => { }) 方法，此方法可用來補充已設定的端點設定：options.Configure(context.Configuration.GetSection("{SECTION}")) returns a KestrelConfigurationLoader with an .Endpoint(string name, listenOptions => { }) method that can be used to supplement a configured endpoint's settings:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                .Endpoint("HTTPS", listenOptions =>
                {
                    listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                });
        });

您可以在方法的選項中使用每個端點的設定區段， Endpoint 以便讀取自訂設定。The configuration section for each endpoint is available on the options in the Endpoint method so that custom settings may be read.
可以藉由使用另一個區段再次呼叫 options.Configure(context.Configuration.GetSection("{SECTION}")) 而載入多個組態。Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. 只會使用最後一個組態，除非在先前的執行個體上已明確呼叫 Load。Only the last configuration is used, unless Load is explicitly called on prior instances. 中繼套件不會呼叫 Load，如此可能會取代其預設組態區段。The metapackage doesn't call Load so that its default configuration section may be replaced.
KestrelConfigurationLoader 會將來自 KestrelServerOptions 的 API 的 Listen 系列鏡像為 Endpoint 多載，所以可在相同的位置設定程式碼和設定端點。KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. 這些多載不使用名稱，並且只使用來自組態的預設組態。These overloads don't use names and only consume default settings from configuration.

變更程式碼中的預設值Change the defaults in code

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, serverOptions) =>
        {
            serverOptions.ConfigureEndpointDefaults(listenOptions =>
            {
                // Configure endpoint defaults
            });

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

SNI 的 Kestrel 支援Kestrel support for SNI

SNI 支援需要：SNI support requires:

在目標 framework netcoreapp2.1 或更新版本上執行。Running on target framework netcoreapp2.1 or later. 在 net461 或更新版本中，會叫用回呼，但 name 一律為 null 。On net461 or later, the callback is invoked but the name is always null. 如果用戶端不在 TLS 信號交換中提供主機名稱參數，則 name 也是 null。The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
所有網站都在相同的 Kestrel 執行個體上執行。All websites run on the same Kestrel instance. 在不使用反向 Proxy 的情況下，Kestrel 不支援跨多個執行個體共用 IP 位址和連接埠。Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel((context, 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;
                    };
                });
            });
        })
        .Build();

連接記錄Connection logging

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

繫結至 TCP 通訊端Bind to a TCP socket

Listen 方法會繫結至 TCP 通訊端，而選項 Lambda 則會允許 X.509 憑證設定：The Listen method binds to a TCP socket, and an options lambda permits X.509 certificate configuration:

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

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

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.Listen(IPAddress.Loopback, 5000);
            serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testPassword");
            });
        });

在 macOS、Linux 和 Windows 上，可以使用 OpenSSL (英文) 建立憑證。On macOS, Linux, and Windows, certificates can be created using OpenSSL.

繫結至 Unix 通訊端Bind to a Unix socket

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .UseKestrel(serverOptions =>
        {
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
            serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", listenOptions =>
            {
                listenOptions.UseHttps("testCert.pfx", "testpassword");
            });
        });

在 Nginx confiuguration 檔案中，將 server > location > proxy_pass 專案設定為 http://unix:/tmp/{KESTREL SOCKET}:/; 。In the Nginx confiuguration file, set the server > location > proxy_pass entry to http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} 這是提供給 (的通訊端名稱 ListenUnixSocket ，例如 kestrel-test.sock 上述範例) 。{KESTREL SOCKET} is the name of the socket provided to ListenUnixSocket (for example, kestrel-test.sock in the preceding example).
確定 Nginx (可寫入通訊端，例如 chmod go+w /tmp/kestrel-test.sock) 。Ensure that the socket is writeable by Nginx (for example, chmod go+w /tmp/kestrel-test.sock).

連接埠 0Port 0

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

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

限制Limitations

使用下列方法來設定端點：Configure endpoints with the following approaches:

UseUrls
--urls 命令列引數--urls command-line argument
urls 主機組態索引鍵urls host configuration key
ASPNETCORE_URLS 環境變數ASPNETCORE_URLS environment variable

HTTPS 無法與這些方法搭配使用，除非在 HTTPS 端點設定中提供預設憑證 (例如，使用 KestrelServerOptions 設定或設定檔，如本主題稍早所示)。HTTPS can't be used with these approaches unless a default certificate is provided in the HTTPS endpoint configuration (for example, using KestrelServerOptions configuration or a configuration file as shown earlier in this topic).
當同時使用 Listen 和 UseUrls 方法時，Listen 端點會覆寫 UseUrls 端點。When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

IIS 端點設定IIS endpoint configuration

Libuv 傳輸設定Libuv transport configuration

Microsoft.AspNetCore.Server.Kestrel (直接套件參考)Microsoft.AspNetCore.Server.Kestrel (direct package reference)
Microsoft.AspNetCore.AppMicrosoft.AspNetCore.App

針對需要使用 Libuv 的專案：For projects that require the use of Libuv:

將 Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv 套件的相依性新增至應用程式的專案檔中：Add a dependency for the Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv package to the app's project file:
```
<PackageReference Include="Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv"
                  Version="{VERSION}" />
```

呼叫 UseLibuv：Call UseLibuv:

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

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

URL 前置詞URL prefixes

IPv4 位址與連接埠號碼IPv4 address with port number
```
http://65.55.39.10:80/
```
0.0.0.0 是繫結至所有 IPv4 位址的特殊情況。0.0.0.0 is a special case that binds to all IPv4 addresses.
IPv6 位址與連接埠號碼IPv6 address with port number
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] 是相當於 IPv4 0.0.0.0 的 IPv6 對等項目。[::] is the IPv6 equivalent of IPv4 0.0.0.0.
主機名稱與連接埠號碼Host name with port number
```
http://contoso.com:80/
http://*:80/
```
主機名稱 * 和 + 並不特殊。Host names, *, and +, aren't special. 無法辨識為有效 IP 位址或 localhost 的任何項目，都會繫結至所有 IPv4 和 IPv6 IP。Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. 若要在相同連接埠上將不同的主機名稱繫結至不同的 ASP.NET Core 應用程式，請使用 HTTP.sys 或反向 Proxy 伺服器 (例如 IIS、Nginx 或 Apache)。To bind different host names to different ASP.NET Core apps on the same port, use HTTP.sys or a reverse proxy server, such as IIS, Nginx, or Apache.

警告

裝載於反向 Proxy 組態需要主機篩選。Hosting in a reverse proxy configuration requires host filtering.
主機 localhost 名稱與連接埠號碼，或回送 IP 與連接埠號碼Host localhost name with port number or loopback IP with port number
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
如果指定 localhost，Kestrel 會嘗試同時繫結至 IPv4 和 IPv6 回送介面。When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. 如果所要求的連接埠在任一個回送介面上由另一個服務使用，則 Kestrel 無法啟動。If the requested port is in use by another service on either loopback interface, Kestrel fails to start. 如果任一回送介面由於任何其他原因 (最常見的原因是不支援 IPv6) 無法使用，Kestrel 就會記錄警告。If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

主機篩選Host filtering

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

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

appsettings.json:appsettings.json:

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

注意

HTTP/1.1 要求清空HTTP/1.1 request draining

用戶端可能已經傳送部分 POST 資料。The client may already have sent part of the POST data.
伺服器會寫入301回應。The server writes the 301 response.
連線無法用於新的要求，直到 POST 前一個要求主體的資料已完全讀取為止。The connection can't be used for a new request until the POST data from the previous request body has been fully read.
Kestrel 會嘗試清空要求主體。Kestrel tries to drain the request body. 清空要求主體表示在不處理資料的情況下讀取和捨棄資料。Draining the request body means reading and discarding the data without processing it.

清空有五秒的時間，無法設定。Draining has a timeout of five seconds, which isn't configurable.
如果或標頭所指定的所有資料在 Content-Length Transfer-Encoding 此時間之前未被讀取，則連接會關閉。If all of the data specified by the Content-Length or Transfer-Encoding header hasn't been read before the timeout, the connection is closed.

呼叫時有一些注意事項 Abort ：There are caveats to calling Abort:

建立新的連接可能很慢且昂貴。Creating new connections can be slow and expensive.
在連接關閉之前，不保證用戶端已讀取回應。There's no guarantee that the client has read the response before the connection closes.
呼叫 Abort 應該很罕見，而且會保留給嚴重的錯誤案例，而不是常見的錯誤。Calling Abort should be rare and reserved for severe error cases, not common errors.
- 只有 Abort 在需要解決特定問題時才呼叫。Only call Abort when a specific problem needs to be solved. 例如， Abort 如果惡意用戶端嘗試 POST 資料或用戶端程式代碼中有錯誤，而導致大量或許多要求，請呼叫。For example, call Abort if malicious clients are trying to POST data or when there's a bug in client code that causes large or numerous requests.
- 請勿呼叫 Abort 常見的錯誤狀況，例如 HTTP 404 (找不到) 。Don't call Abort for common error situations, such as HTTP 404 (Not Found).

其他資源Additional resources

在 Linux 上使用 UNIX 通訊端時，通訊端不會在應用程式關閉時自動刪除。When using UNIX sockets on Linux, the socket is not automatically deleted on app shut down. 如需詳細資訊，請參閱此 GitHub 問題。For more information, see this GitHub issue.
針對 ASP.NET Core 專案進行疑難排解和調試
在 ASP.NET Core 中強制使用 HTTPS
設定 ASP.NET Core 以與 Proxy 伺服器和負載平衡器搭配運作
RFC 7230：訊息語法和路由 (第 5.4 節：主機)RFC 7230: Message Syntax and Routing (Section 5.4: Host)