Kestrel web server implementation in ASP.NET Core

我会带着你远行 2023-06-01 05:38 43阅读 0赞

[https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?tabs=aspnetcore1x&view=aspnetcore-2.2][https_docs.microsoft.com_en-us_aspnet_core_fundamentals_servers_kestrel_tabs_aspnetcore1x_view_aspnetcore-2.2]

By [Tom Dykstra][], [Chris Ross][], and [Stephen Halter][]

Kestrel is a cross-platform [web server for ASP.NET Core][]. Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel supports the following scenarios:

*  HTTPS
 *  Opaque upgrade used to enable [WebSockets][]
 *  Unix sockets for high performance behind Nginx
 *  HTTP/2 (except on macOS†)

†HTTP/2 will be supported on macOS in a future release.

Kestrel is supported on all platforms and versions that .NET Core supports.

[View or download sample code][] ([how to download][])

## HTTP/2 support ##

[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 or later‡
     *  Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
 *  Target framework: .NET Core 2.2 or later
 *  [Application-Layer Protocol Negotiation (ALPN)][Application-Layer Protocol Negotiation _ALPN] connection
 *  TLS 1.2 or later connection

†HTTP/2 will be supported on macOS in a future release. ‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

If an HTTP/2 connection is established, [HttpRequest.Protocol][] reports `HTTP/2`.

HTTP/2 is disabled by default. For more information on configuration, see the [Kestrel options][] and [ListenOptions.Protocols][] sections.

## When to use Kestrel with a reverse proxy ##

Kestrel can be used by itself or with a *reverse proxy server*, such as [Internet Information Services (IIS)][Internet Information Services _IIS], [Nginx][], or [Apache][]. A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel used as an edge (Internet-facing) web server:

![Kestrel communicates directly with the Internet without a reverse proxy server][]

Kestrel used in a reverse proxy configuration:

![Kestrel communicates indirectly with the Internet through a reverse proxy server, such as IIS, Nginx, or Apache][Kestrel communicates indirectly with the Internet through a reverse proxy server_ such as IIS_ Nginx_ or Apache]

Either configuration—with or without a reverse proxy server—is a supported hosting configuration for ASP.NET Core 2.1 or later apps that receive requests from the Internet.

Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' `Host` headers. A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

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.
 *  Simplify load balancing and secure communication (HTTPS) configuration. Only the reverse proxy server requires an X.509 certificate, and that server can communicate with your app servers on the internal network using plain HTTP.

Warning

Hosting in a reverse proxy configuration requires [host filtering][].

## How to use Kestrel in ASP.NET Core apps ##

The [Microsoft.AspNetCore.Server.Kestrel][] package is included in the [Microsoft.AspNetCore.App metapackage][] (ASP.NET Core 2.1 or later).

ASP.NET Core project templates use Kestrel by default. In *Program.cs*, the template code calls [CreateDefaultBuilder][], which calls [UseKestrel][] behind the scenes.

To provide additional configuration after calling `CreateDefaultBuilder`, use `ConfigureKestrel`:

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, options) =>
            {
                // Set properties and call methods on options
            })
            .Build();
    
        host.Run();
    }

## Kestrel options ##

The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Set constraints on the [Limits][] property of the [KestrelServerOptions][] class. The `Limits` property holds an instance of the [KestrelServerLimits][] class.

The following examples use the [Microsoft.AspNetCore.Server.Kestrel.Core][] namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

### Keep-alive timeout ###

[KeepAliveTimeout][]

Gets or sets the [keep-alive timeout][]. Defaults to 2 minutes.

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

### Maximum client connections ###

[MaxConcurrentConnections][] [MaxConcurrentUpgradedConnections][]

The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

There's a separate limit for connections that have been upgraded from HTTP or HTTPS to another protocol (for example, on a WebSockets request). After a connection is upgraded, it isn't counted against the `MaxConcurrentConnections` limit.

The maximum number of connections is unlimited (null) by default.

### Maximum request body size ###

[MaxRequestBodySize][]

The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

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:

An exception is thrown if you attempt to configure the limit on a request after the app has started to read the request. 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.

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 checks every second if data is arriving at the specified rate in bytes/second. 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. The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

The default minimum rate is 240 bytes/second with a 5 second grace period.

A minimum rate also applies to the 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.

Here's an example that shows how to configure the minimum data rates in *Program.cs*:

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

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. 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. Defaults to 30 seconds.

### Maximum streams per connection ###

`Http2.MaxStreamsPerConnection` limits the number of concurrent request streams per HTTP/2 connection. Excess streams are refused.

The default value is 100.

### Header table size ###

The HPACK decoder decompresses HTTP headers for HTTP/2 connections. `Http2.HeaderTableSize`limits the size of the header compression table that the HPACK decoder uses. The value is provided in octets and must be greater than zero (0).

The default value is 4096.

### Maximum frame size ###

`Http2.MaxFrameSize` indicates the maximum size of the HTTP/2 connection frame payload to receive. The value is provided in octets and must be between 2^14 (16,384) and 2^24-1 (16,777,215).

The default value is 2^14 (16,384).

### Maximum request header size ###

`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. The value must be greater than zero (0).

The default value is 8,192.

### Initial connection window size ###

`Http2.InitialConnectionWindowSize` indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Requests are also limited by `Http2.InitialStreamWindowSize`. The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

The default value is 128 KB (131,072).

### Initial stream window size ###

`Http2.InitialStreamWindowSize` indicates the maximum request body data in bytes the server buffers at one time per request (stream). Requests are also limited by `Http2.InitialStreamWindowSize`. The value must be greater than or equal to 65,535 and less than 2^31 (2,147,483,648).

The default value is 96 KB (98,304).

### Synchronous IO ###

[AllowSynchronousIO][] controls whether synchronous IO is allowed for the request and response. The default value is `true`.

Warning

A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous IO.

The following example enables synchronous IO:

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

For information about other Kestrel options and limits, see:

*  [KestrelServerOptions][]
 *  [KestrelServerLimits][]
 *  [ListenOptions][]

## Endpoint configuration ##

By default, ASP.NET Core binds to:

*  `http://localhost:5000`
 *  `https://localhost:5001` (when a local development certificate is present)

Specify URLs using the:

*  `ASPNETCORE_URLS` environment variable.
 *  `--urls` command-line argument.
 *  `urls` host configuration key.
 *  `UseUrls` extension method.

The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configure the value as a semicolon-separated list (for example, `"Urls": "http://localhost:8000;http://localhost:8001"`).

For more information on these approaches, see [Server URLs][] and [Override configuration][].

A development certificate is created:

*  When the [.NET Core SDK][] is installed.
 *  The [dev-certs tool][] is used to create a certificate.

Some browsers require that you grant explicit permission to the browser to trust the local development certificate.

ASP.NET Core 2.1 and later project templates configure apps to run on HTTPS by default and include [HTTPS redirection and HSTS support][].

Call [Listen][] or [ListenUnixSocket][] methods on [KestrelServerOptions][] to configure URL prefixes and ports for Kestrel.

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

ASP.NET Core 2.1 or later `KestrelServerOptions` configuration:

### ConfigureEndpointDefaults(Action<ListenOptions>) ###

Specifies a configuration `Action` to run for each specified endpoint. Calling `ConfigureEndpointDefaults` multiple times replaces prior `Action`s with the last `Action` specified.

### ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) ###

Specifies a configuration `Action` to run for each HTTPS endpoint. Calling `ConfigureHttpsDefaults`multiple times replaces prior `Action`s with the last `Action` specified.

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

### Configure(IConfiguration) ###

Creates a configuration loader for setting up Kestrel that takes an [IConfiguration][] as input. The configuration must be scoped to the configuration section for Kestrel.

### ListenOptions.UseHttps ###

Configure Kestrel to use HTTPS.

`ListenOptions.UseHttps` extensions:

*  `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` parameters:

*  `filename` is the path and file name of a certificate file, relative to the directory that contains the app's content files.
 *  `password` is the password required to access the X.509 certificate data.
 *  `configureOptions` is an `Action` to configure the `HttpsConnectionAdapterOptions`. Returns the `ListenOptions`.
 *  `storeName` is the certificate store from which to load the certificate.
 *  `subject` is the subject name for the certificate.
 *  `allowInvalid` indicates if invalid certificates should be considered, such as self-signed certificates.
 *  `location` is the store location to load the certificate from.
 *  `serverCertificate` is the X.509 certificate.

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 listens on `http://localhost:5000` and `https://localhost:5001` (if a default cert is available).

*Replace the default certificate from configuration*

[CreateDefaultBuilder][] calls `serverOptions.Configure(context.Configuration.GetSection("Kestrel"))`by default to load Kestrel configuration. A default HTTPS app settings configuration schema is available for Kestrel. Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

In the following *appsettings.json* example:

*  Set AllowInvalid to `true` to permit the use of invalid certificates (for example, self-signed certificates).
 *  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. For example, `HTTPS` and `Https` are valid.
 *  The `Url` parameter is required for each endpoint. The format for this parameter is the same as the top-level `Urls` configuration parameter except that it's limited to a single value.
 *  These endpoints replace those defined in the top-level `Urls` configuration rather than adding to them. Endpoints defined in code via `Listen` are cumulative with the endpoints defined in the configuration section.
 *  The `Certificate` section is optional. 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.
 *  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("Kestrel"))` returns a `KestrelConfigurationLoader` with an `.Endpoint(string name, options => { })` method that can be used to supplement a configured endpoint's settings:
    
        options.Configure(context.Configuration.GetSection("Kestrel"))
            .Endpoint("HTTPS", opt =>
            {
                opt.HttpsOptions.SslProtocols = SslProtocols.Tls12;
            });
    
    You can also directly access `KestrelServerOptions.ConfigurationLoader` to keep iterating on the existing loader, such as the one provided by [CreateDefaultBuilder][].
 *  The configuration section for each endpoint is a available on the options in the `Endpoint`method so that custom settings may be read.
 *  Multiple configurations may be loaded by calling `options.Configure(context.Configuration.GetSection("Kestrel"))` again with another section. Only the last configuration is used, unless `Load` is explicitly called on prior instances. The metapackage doesn't call `Load` so that its default configuration section may be replaced.
 *  `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` and `ConfigureHttpsDefaults` can be used to change default settings for `ListenOptions` and `HttpsConnectionAdapterOptions`, including overriding the default certificate specified in the prior scenario. `ConfigureEndpointDefaults` and `ConfigureHttpsDefaults` should be called before any endpoints are configured.

options.ConfigureEndpointDefaults(opt =>
    {
        opt.NoDelay = true;
    });
    
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        httpsOptions.SslProtocols = SslProtocols.Tls12;
    });

*Kestrel support for SNI*

[Server Name Indication (SNI)][Server Name Indication _SNI] can be used to host multiple domains on the same IP address and port. 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. The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

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 support requires:

*  Running on target framework `netcoreapp2.1`. On `netcoreapp2.0` and `net461`, the callback is invoked but the `name` is always `null`. The `name` is also `null` if the client doesn't provide the host name parameter in the TLS handshake.
 *  All websites run on the same Kestrel instance. 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, options) =>
            {
                options.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;
                        };
                    });
                });
            });

### Bind to a TCP socket ###

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, options) =>
            {
                options.Listen(IPAddress.Loopback, 5000);
                options.Listen(IPAddress.Loopback, 5001, listenOptions =>
                {
                    listenOptions.UseHttps("testCert.pfx", "testPassword");
                });
            });

The example configures HTTPS for an endpoint with [ListenOptions][]. Use the same API to configure other Kestrel settings for specific endpoints.

On Windows, self-signed certificates can be created using the [New-SelfSignedCertificate PowerShell cmdlet][]. For an unsupported example, see [UpdateIISExpressSSLForChrome.ps1][].

On macOS, Linux, and Windows, certificates can be created using [OpenSSL][].

### Bind to a Unix socket ###

Listen on a Unix socket with [ListenUnixSocket][] for improved performance with Nginx, as shown in this example:

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

### Port 0 ###

When the port number `0` is specified, Kestrel dynamically binds to an available port. 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` command-line argument
 *  `urls` host configuration key
 *  `ASPNETCORE_URLS` environment variable

These methods are useful for making code work with servers other than Kestrel. However, be aware of the following limitations:

*  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).
 *  When both the `Listen` and `UseUrls` approaches are used simultaneously, the `Listen`endpoints override the `UseUrls` endpoints.

### IIS endpoint configuration ###

When using IIS, the URL bindings for IIS override bindings are set by either `Listen` or `UseUrls`. For more information, see the [ASP.NET Core Module][] topic.

### ListenOptions.Protocols ###

The `Protocols` property establishes the HTTP protocols (`HttpProtocols`) enabled on a connection endpoint or for the server. Assign a value to the `Protocols` property from the `HttpProtocols` enum.

<table> 
 <thead> 
  <tr> 
   <th><code>HttpProtocols</code>enum value</th> 
   <th>Connection protocol permitted</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>Http1</code></td> 
   <td>HTTP/1.1 only. Can be used with or without TLS.</td> 
  </tr> 
  <tr> 
   <td><code>Http2</code></td> 
   <td>HTTP/2 only. Primarily used with TLS. May be used without TLS only if the client supports a&nbsp;<a href="https://tools.ietf.org/html/rfc7540#section-3.4" rel="nofollow">Prior Knowledge mode</a>.</td> 
  </tr> 
  <tr> 
   <td><code>Http1AndHttp2</code></td> 
   <td>HTTP/1.1 and HTTP/2. Requires a TLS and&nbsp;<a href="https://tools.ietf.org/html/rfc7301#section-3" rel="nofollow">Application-Layer Protocol Negotiation (ALPN)</a>connection to negotiate HTTP/2; otherwise, the connection defaults to HTTP/1.1.</td> 
  </tr> 
 </tbody> 
</table>

The default protocol is HTTP/1.1.

TLS restrictions for HTTP/2:

*  TLS version 1.2 or later
 *  Renegotiation disabled
 *  Compression disabled
 *  Minimum ephemeral key exchange sizes:
    
     *  Elliptic curve Diffie-Hellman (ECDHE) \[[RFC4492][]\] – 224 bits minimum
     *  Finite field Diffie-Hellman (DHE) \[`TLS12`\] – 2048 bits minimum
 *  Cipher suite not blacklisted

`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` \[`TLS-ECDHE`\] with the P-256 elliptic curve \[`FIPS186`\] is supported by default.

The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Connections are secured by TLS with a supplied certificate:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .ConfigureKestrel((context, options) =>
            {
                options.Listen(IPAddress.Any, 8000, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
                    listenOptions.UseHttps("testCert.pfx", "testPassword");
                });
            });

Optionally create an `IConnectionAdapter` implementation to filter TLS handshakes on a per-connection basis for specific ciphers:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .ConfigureKestrel((context, options) =>
            {
                options.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 you don't
            // wish to support. Alternatively, define and compare
            // ITlsHandshakeFeature.CipherAlgorithm to a list of acceptable cipher
            // suites.
            //
            // A ITlsHandshakeFeature.CipherAlgorithm of CipherAlgorithmType.Null
            // indicates that no cipher algorithm supported by Kestrel matches the
            // requested algorithm(s).
            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][] calls `serverOptions.Configure(context.Configuration.GetSection("Kestrel"))`by default to load Kestrel configuration.

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.

## Transport configuration ##

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. 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][] (direct package reference)
 *  [Microsoft.AspNetCore.App][]

For ASP.NET Core 2.1 or later projects that use the [Microsoft.AspNetCore.App metapackage][] and require the use of 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="<LATEST_VERSION>" />
 *  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 prefixes ###

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.

Only HTTP URL prefixes are valid. Kestrel doesn't support HTTPS when configuring URL bindings using `UseUrls`.

*  IPv4 address with port number
    
        http://65.55.39.10:80/
    
    `0.0.0.0` is a special case that binds to all IPv4 addresses.
 *  IPv6 address with port number
    
        http://[0:0:0:0:0:ffff:4137:270a]:80/
    
    `[::]` 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. Anything not recognized as a valid IP address or `localhost` binds to all IPv4 and IPv6 IPs. 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.
    
     Warning
    
    Hosting in a reverse proxy configuration requires [host filtering][].
 *  Host `localhost` name with port number or loopback IP with port number
    
        http://localhost:5000/
        http://127.0.0.1:5000/
        http://[::1]:5000/
    
    When `localhost` is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. If the requested port is in use by another service on either loopback interface, Kestrel fails to start. If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

## Host filtering ##

While Kestrel supports configuration based on prefixes such as `http://example.com:5000`, Kestrel largely ignores the host name. Host `localhost` is a special case used for binding to loopback addresses. Any host other than an explicit IP address binds to all public IP addresses. `Host` headers aren't validated.

As a workaround, use Host Filtering Middleware. 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 later). 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. 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*:

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

Note

[Forwarded Headers Middleware][] also has an [AllowedHosts][] option. Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. 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. 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.

For more information on Forwarded Headers Middleware, see [Configure ASP.NET Core to work with proxy servers and load balancers][Forwarded Headers Middleware].

## Additional resources ##

*  [Troubleshoot ASP.NET Core projects][]
 *  [Enforce HTTPS in ASP.NET Core][HTTPS redirection and HSTS support]
 *  [Configure ASP.NET Core to work with proxy servers and load balancers][Forwarded Headers Middleware]
 *  [Kestrel source code][]
 *  [RFC 7230: Message Syntax and Routing (Section 5.4: Host)][RFC 7230_ Message Syntax and Routing _Section 5.4_ Host]

转载于:https://www.cnblogs.com/Jeely/p/11357014.html

[https_docs.microsoft.com_en-us_aspnet_core_fundamentals_servers_kestrel_tabs_aspnetcore1x_view_aspnetcore-2.2]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?tabs=aspnetcore1x&view=aspnetcore-2.2
[Tom Dykstra]: https://github.com/tdykstra
[Chris Ross]: https://github.com/Tratcher
[Stephen Halter]: https://twitter.com/halter73
[web server for ASP.NET Core]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/index?view=aspnetcore-2.2
[WebSockets]: https://github.com/aspnet/websockets
[View or download sample code]: https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/fundamentals/servers/kestrel/samples
[how to download]: https://docs.microsoft.com/en-us/aspnet/core/index?view=aspnetcore-2.2#how-to-download-a-sample
[HTTP_2]: https://httpwg.org/specs/rfc7540.html
[Application-Layer Protocol Negotiation _ALPN]: https://tools.ietf.org/html/rfc7301#section-3
[HttpRequest.Protocol]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.http.httprequest.protocol
[Kestrel options]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?tabs=aspnetcore1x&view=aspnetcore-2.2#kestrel-options
[ListenOptions.Protocols]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?tabs=aspnetcore1x&view=aspnetcore-2.2#listenoptionsprotocols
[Internet Information Services _IIS]: https://www.iis.net/
[Nginx]: https://nginx.org/
[Apache]: https://httpd.apache.org/
[Kestrel communicates directly with the Internet without a reverse proxy server]: /images/20230601/c2dd519ce91a42eb873195d2cb71332e.png
[Kestrel communicates indirectly with the Internet through a reverse proxy server_ such as IIS_ Nginx_ or Apache]: /images/20230601/a5ae14a42c9f4c8383ca9704f501aa97.png
[host filtering]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?tabs=aspnetcore1x&view=aspnetcore-2.2#host-filtering
[Microsoft.AspNetCore.Server.Kestrel]: https://www.nuget.org/packages/Microsoft.AspNetCore.Server.Kestrel/
[Microsoft.AspNetCore.App metapackage]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/metapackage-app?view=aspnetcore-2.2
[CreateDefaultBuilder]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder
[UseKestrel]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderkestrelextensions.usekestrel
[Limits]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.limits#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerOptions_Limits
[KestrelServerOptions]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions
[KestrelServerLimits]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits
[Microsoft.AspNetCore.Server.Kestrel.Core]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core
[KeepAliveTimeout]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.keepalivetimeout#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_KeepAliveTimeout
[keep-alive timeout]: https://tools.ietf.org/html/rfc7230#section-6.5
[MaxConcurrentConnections]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.maxconcurrentconnections#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_MaxConcurrentConnections
[MaxConcurrentUpgradedConnections]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.maxconcurrentupgradedconnections#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_MaxConcurrentUpgradedConnections
[MaxRequestBodySize]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.maxrequestbodysize#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_MaxRequestBodySize
[RequestSizeLimitAttribute]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.requestsizelimitattribute
[out-of-process]: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/index?view=aspnetcore-2.2#out-of-process-hosting-model
[ASP.NET Core Module]: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/aspnet-core-module?view=aspnetcore-2.2
[MinRequestBodyDataRate]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.minrequestbodydatarate#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_MinRequestBodyDataRate
[MinResponseDataRate]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.minresponsedatarate#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_MinResponseDataRate
[RequestHeadersTimeout]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserverlimits.requestheaderstimeout#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerLimits_RequestHeadersTimeout
[AllowSynchronousIO]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.allowsynchronousio#Microsoft_AspNetCore_Server_Kestrel_Core_KestrelServerOptions_AllowSynchronousIO
[ListenOptions]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.listenoptions
[Server URLs]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/web-host?view=aspnetcore-2.2#server-urls
[Override configuration]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/web-host?view=aspnetcore-2.2#override-configuration
[.NET Core SDK]: https://docs.microsoft.com/en-us/dotnet/core/sdk
[dev-certs tool]: https://docs.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-2.1?view=aspnetcore-2.2#https
[HTTPS redirection and HSTS support]: https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-2.2
[Listen]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.listen
[ListenUnixSocket]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions.listenunixsocket
[IConfiguration]: https://docs.microsoft.com/dotnet/api/microsoft.extensions.configuration.iconfiguration
[Server Name Indication _SNI]: https://tools.ietf.org/html/rfc6066#section-3
[New-SelfSignedCertificate PowerShell cmdlet]: https://docs.microsoft.com/en-us/powershell/module/pkiclient/new-selfsignedcertificate?view=win10-ps
[UpdateIISExpressSSLForChrome.ps1]: https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/includes/make-x509-cert/UpdateIISExpressSSLForChrome.ps1
[OpenSSL]: https://www.openssl.org/
[UseUrls]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.hostingabstractionswebhostbuilderextensions.useurls
[RFC4492]: https://www.ietf.org/rfc/rfc4492.txt
[UseLibuv]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.hosting.webhostbuilderlibuvextensions.uselibuv
[Microsoft.AspNetCore.App]: https://www.nuget.org/packages/Microsoft.AspNetCore.App/
[Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv]: https://www.nuget.org/packages/Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv/
[HTTP.sys]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/httpsys?view=aspnetcore-2.2
[Microsoft.AspNetCore.HostFiltering]: https://www.nuget.org/packages/Microsoft.AspNetCore.HostFiltering
[AddHostFiltering]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.hostfilteringservicesextensions.addhostfiltering
[Forwarded Headers Middleware]: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-2.2
[AllowedHosts]: https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions.allowedhosts#Microsoft_AspNetCore_Builder_ForwardedHeadersOptions_AllowedHosts
[Troubleshoot ASP.NET Core projects]: https://docs.microsoft.com/en-us/aspnet/core/test/troubleshoot?view=aspnetcore-2.2
[Kestrel source code]: https://github.com/aspnet/AspNetCore/tree/master/src/Servers/Kestrel
[RFC 7230_ Message Syntax and Routing _Section 5.4_ Host]: https://tools.ietf.org/html/rfc7230#section-5.4