Implementazione del server Web Kestrel in ASP.NET CoreKestrel web server implementation in ASP.NET Core

Di Tom Dykstra, Chris Ross, Stephen Haltere Luke LathamBy Tom Dykstra, Chris Ross, Stephen Halter, and Luke Latham

Kestrel è un server Web per ASP.NET Core multipiattaforma.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel è il server Web incluso per impostazione predefinita nei modelli di progetto di ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel supporta gli scenari seguenti:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Aggiornamento opaco usato per abilitare WebSocketOpaque upgrade used to enable WebSockets
  • Socket Unix ad alte prestazioni dietro NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (tranne che in macOS†)HTTP/2 (except on macOS†)

†HTTP/2 verrà supportato in macOS in una versione futura.†HTTP/2 will be supported on macOS in a future release.

Kestrel è supportato in tutte le piattaforme e le versioni supportate da .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Supporto per HTTP/2HTTP/2 support

HTTP/2 è disponibile per le app ASP.NET Core se vengono soddisfatti i requisiti di base seguenti:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operativo†Operating system†
    • Windows Server 2016/Windows 10 o versioni successive‡Windows Server 2016/Windows 10 or later‡
    • Linux con OpenSSL 1.0.2 o versioni successive (ad esempio, Ubuntu 16.04 o versioni successive)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Framework di destinazione: .NET Core 2.2 o versioni successiveTarget framework: .NET Core 2.2 or later
  • Connessione ALPN (Application-Layer Protocol Negotiation)Application-Layer Protocol Negotiation (ALPN) connection
  • Connessione TLS 1.2 o successivaTLS 1.2 or later connection

†HTTP/2 verrà supportato in macOS in una versione futura.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel ha un supporto limitato per HTTP/2 in Windows Server 2012 R2 e Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Il supporto è limitato perché l'elenco di suite di crittografia TLS supportate disponibili in questi sistemi operativi è limitato.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Un certificato generato con un algoritmo ECDSA potrebbe essere necessario per proteggere le connessioni TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Se viene stabilita una connessione HTTP/2, HttpRequest.Protocol corrisponde a HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 è disabilitato per impostazione predefinita.HTTP/2 is disabled by default. Per altre informazioni sulla configurazione, vedere le sezioni Opzioni Kestrel e ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Quando usare Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

È possibile usare Kestrel da solo o in combinazione con un server proxy inverso, ad esempio Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Il server proxy inverso riceve le richieste HTTP dalla rete e le inoltra a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usato come server Web perimetrale (esposto a Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel comunica direttamente con Internet senza un server proxy inverso

Kestrel usato in una configurazione proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel comunica indirettamente con Internet attraverso un server proxy inverso, ad esempio IIS, Nginx o Apache

La configurazione, con o senza un server proxy inverso, è una configurazione di hosting supportata.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Se viene utilizzato come server perimetrale in assenza di un server proxy inverso, Kestrel non supporta la condivisione tra più processi dell'IP e della porta.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando è configurato per restare in ascolto su una porta, Kestrel gestisce tutto il traffico per tale porta indipendentemente dalle intestazioni Host delle richieste.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Un proxy inverso che può condividere le porte può eseguire l'inoltro delle richieste a Kestrel su un unico IP e un'unica porta.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Anche se la presenza di un server proxy inverso non è necessaria, può risultare utile per i motivi seguenti.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso:A reverse proxy:

  • Può limitare l'area della superficie di attacco pubblica esposta delle app ospitate.Can limit the exposed public surface area of the apps that it hosts.
  • Offre un livello aggiuntivo di configurazione e protezione.Provide an additional layer of configuration and defense.
  • Potrebbe offrire un'integrazione migliore con l'infrastruttura esistente.Might integrate better with existing infrastructure.
  • Semplifica il bilanciamento del carico e la configurazione di comunicazioni protette (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solo il server proxy inverso richiede un certificato X. 509 e il server è in grado di comunicare con i server dell'app nella rete interna tramite HTTP normale.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.

Avviso

Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

Come usare Kestrel nelle app ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

I modelli di progetto ASP.NET Core usano Kestrel per impostazione predefinita.ASP.NET Core project templates use Kestrel by default. In Program.cs il codice del modello chiama CreateDefaultBuilder, che chiama UseKestrel in background.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

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

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

Per fornire una configurazione aggiuntiva CreateDefaultBuilder dopo ConfigureWebHostDefaultsavere chiamato ConfigureKestrele, usare:To provide additional configuration after calling CreateDefaultBuilder and 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>();
        });

Se l'app non chiama CreateDefaultBuilder per configurare l'host, chiamare UseKestrel prima di chiamare 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 HostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseIISIntegration()
            .UseStartup<Startup>();
        })
        .Build();

    host.Run();
}

Opzioni KestrelKestrel options

Il server Web Kestrel dispone di opzioni di configurazione dei vincoli che risultano particolarmente utili nelle distribuzioni con connessione Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Impostare i vincoli per la proprietà Limits della classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La proprietà Limits contiene un'istanza della classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Negli esempi seguenti viene usato lo spazio dei nomi Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Timeout keep-aliveKeep-alive timeout

KeepAliveTimeout

Ottiene o imposta il timeout keep-alive.Gets or sets the keep-alive timeout. Il valore predefinito è 2 minuti.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);
})

Numero massimo di connessioni clientMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

È possibile impostare il numero massimo di connessioni TCP aperte simultaneamente per l'intera app con il codice seguente: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);
})

È previsto un limite separato per le connessioni che sono state aggiornate da HTTP o HTTPS a un altro protocollo (ad esempio su una richiesta 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). Dopo l'aggiornamento di una connessione, questa non viene conteggiata per il limite 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);
})

Per impostazione predefinita, il numero massimo di connessioni è illimitato (null).The maximum number of connections is unlimited (null) by default.

Dimensione massima del corpo della richiestaMaximum request body size

MaxRequestBodySize

La dimensione massima predefinita del corpo della richiesta è pari a 30.000.000 di byte, equivalenti a circa 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Il metodo consigliato per ignorare il limite in un'app ASP.NET Core MVC è l'uso dell'attributo RequestSizeLimitAttribute in un metodo di azione: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()

L'esempio seguente illustra come configurare il vincolo per l'app in ogni richiesta: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);
})

Eseguire l'override dell'impostazione per una richiesta specifica nel middleware: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));
    }

Viene generata un'eccezione se l'app configura il limite per una richiesta dopo che l'app ha iniziato a leggere la richiesta.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Una proprietà IsReadOnly indica se la proprietà MaxRequestBodySize è in stato di sola lettura e pertanto è troppo tardi per configurare il limite.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.

Quando un'app viene eseguita out-of-process dietro il modulo ASP.NET Core, il limite della dimensione del corpo della richiesta di Kestrel è disabilitato perché viene già impostato da 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.

Velocità minima dei dati del corpo della richiestaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel controlla ogni secondo se i dati arrivano alla velocità in byte al secondo specificata.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se la velocità scende sotto il valore minimo, la connessione raggiunge il timeout. Il periodo di tolleranza è la quantità di tempo che Kestrel concede al client per aumentare la velocità di trasmissione fino al valore minimo. Durante tale periodo la velocità non viene rilevata.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. Il periodo di prova consente di evitare l'interruzione di connessioni che inizialmente inviano i dati a velocità ridotta a causa dell'avvio lento del protocollo TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocità minima predefinita è di 240 byte al secondo, con un periodo di tolleranza di 5 secondi.The default minimum rate is 240 bytes/second with a 5 second grace period.

Anche per la risposta è prevista una velocità minima.A minimum rate also applies to the response. Il codice per impostare il limite della richiesta e della risposta è identico e varia solo per RequestBody o Response nei nomi di proprietà e di interfaccia.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.

L'esempio seguente visualizza come configurare la velocità minima dei dati in 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);
})

Ignorare i limiti di velocità minima per ogni richiesta nel middleware: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));
    }

La funzionalità IHttpMinResponseDataRateFeature a cui si fa riferimento nell'esempio precedente non è presente in HttpContext.Features per le richieste HTTP/2, perché la modifica dei limiti di velocità per ogni richiesta in genere non è supportata per HTTP/2 a causa del supporto del protocollo per il multiplexing delle richieste.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. La funzionalità IHttpMinRequestBodyDataRateFeature è tuttavia ancora presente in HttpContext.Features per le richieste HTTP/2, perché il limite di velocità di lettura può comunque essere disabilitato interamente per ogni singola richiesta impostando IHttpMinRequestBodyDataRateFeature.MinDataRate su null anche per una richiesta 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. Il tentativo di leggere IHttpMinRequestBodyDataRateFeature.MinDataRate o il tentativo di impostazione di un valore diverso da null causerà la generazione di una NotSupportedException per una richiesta 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.

I limiti di velocità a livello di server configurati tramite KestrelServerOptions.Limits vengono tuttavia applicati alle connessioni HTTP/1.x e HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Timeout delle intestazioni delle richiesteRequest headers timeout

RequestHeadersTimeout

Ottiene o imposta la quantità massima di tempo che il server dedica alla ricezione delle intestazioni delle richieste.Gets or sets the maximum amount of time the server spends receiving request headers. Il valore predefinito è 30 secondi.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);
})

Numero massimo di flussi per connessioneMaximum streams per connection

Http2.MaxStreamsPerConnection limita il numero di flussi di richieste simultanee per ogni connessione HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. I flussi in eccesso vengono rifiutati.Excess streams are refused.

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

Il valore predefinito è 100.The default value is 100.

Dimensioni della tabella delle intestazioniHeader table size

Il decodificatore HPACK decomprime le intestazioni HTTP per le connessioni HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limita le dimensioni della tabella di compressione delle intestazioni usata dal decodificatore HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Il valore viene specificato in ottetti e deve essere maggiore di zero (0).The value is provided in octets and must be greater than zero (0).

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

Il valore predefinito è 4096.The default value is 4096.

Dimensione massima del frameMaximum frame size

Http2.MaxFrameSizeindica la dimensione massima consentita di un payload del frame di connessione HTTP/2 ricevuto o inviato dal server.Http2.MaxFrameSize indicates the maximum allowed size of an HTTP/2 connection frame payload received or sent by the server. Il valore viene specificato in ottetti e deve essere compreso tra 2^14 (16.384) e 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).

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

Il valore predefinito è 2^14 (16.384).The default value is 2^14 (16,384).

Dimensioni massime dell'intestazione della richiestaMaximum request header size

Http2.MaxRequestHeaderFieldSize indica le dimensioni massime consentite in ottetti di valori di intestazione di richiesta.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Questo limite si applica sia al nome che al valore nelle rappresentazioni compresse e non compresse.This limit applies to both name and value in their compressed and uncompressed representations. Il valore deve essere maggiore di zero (0).The value must be greater than zero (0).

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

Il valore predefinito è 8.192.The default value is 8,192.

Dimensioni della finestra di connessione inizialiInitial connection window size

Http2.InitialConnectionWindowSize indica il numero massimo di byte di dati del corpo della richiesta che il server memorizza nel buffer in una volta, aggregati in tutte le richieste (flussi), per ogni connessione.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Le richieste sono anche limitate da Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. Il valore deve essere maggiore di o uguale a 65.535 e minore di 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).

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

Il valore predefinito è 128 KB (131.072).The default value is 128 KB (131,072).

Dimensioni della finestra di flusso inizialiInitial stream window size

Http2.InitialStreamWindowSize indica il numero massimo di byte di dati del corpo della richiesta che il server memorizza nel buffer in una volta per ogni richiesta (flusso).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Le richieste sono anche limitate da Http2.InitialConnectionWindowSize.Requests are also limited by Http2.InitialConnectionWindowSize. Il valore deve essere maggiore di o uguale a 65.535 e minore di 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).

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

Il valore predefinito è 96 KB (98.304).The default value is 96 KB (98,304).

I/O sincronoSynchronous IO

AllowSynchronousIO controlla se l'I/O sincrono è consentito per la richiesta e la risposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. Il valore predefinito è false.The default value is false.

Avviso

Un numero elevato di operazioni di I/O sincrone bloccanti può portare alla scadenza del pool di thread, a causa della quale l'app smette di rispondere.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Abilitare solo AllowSynchronousIO quando si usa una libreria che non supporta l'I/O asincrono.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

L'esempio seguente abilita l'I/O sincrono:The following example enables synchronous IO:

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

Per informazioni su altre opzioni e limiti di Kestrel, vedere:For information about other Kestrel options and limits, see:

Configurazione dell'endpointEndpoint configuration

Per impostazione predefinita, ASP.NET Core è associato a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando è presente un certificato di sviluppo locale)https://localhost:5001 (when a local development certificate is present)

Specificare gli URL usando gli elementi seguenti:Specify URLs using the:

  • La variabile di ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • L'argomento della riga di comando --urls.--urls command-line argument.
  • La chiave di configurazione dell'host urls.urls host configuration key.
  • Il metodo di estensione UseUrls.UseUrls extension method.

Il valore specificato usando i metodi seguenti può essere uno o più endpoint HTTP e HTTPS (HTTPS se è disponibile un certificato predefinito).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configurare il valore come un elenco delimitato da punto e virgola (ad esempio, "Urls": "http://localhost:8000; http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Per altre informazioni su questi approcci, vedere URL del server e Override della configurazione.For more information on these approaches, see Server URLs and Override configuration.

Viene creato un certificato di sviluppo nei casi seguenti:A development certificate is created:

Alcuni browser richiedono la concessione di autorizzazioni esplicite per considerare attendibile il certificato di sviluppo locale.Some browsers require granting explicit permission to trust the local development certificate.

I modelli di progetto consentono di configurare le app per l'esecuzione su HTTPS per impostazione predefinita e includono il reindirizzamento HTTPS e il supporto HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chiamare i metodi Listen oppure ListenUnixSocket su KestrelServerOptions per configurare le porte e i prefissi URL per Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

Anche UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls e la variabile di ambiente ASPNETCORE_URLS funzionano, ma con le limitazioni indicate più avanti nella sezione (deve essere disponibile un certificato predefinito per la configurazione dell'endopoint 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).

KestrelServerOptionsconfigurazioneKestrelServerOptions configuration:

ConfigureEndpointDefaults (azione<ListenOptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint specificato.Specifies a configuration Action to run for each specified endpoint. Se si chiama ConfigureEndpointDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureEndpointDefaults(listenOptions =>
                {
                    // Configure endpoint defaults
                });
            })
            .UseStartup<Startup>();
        });
}

ConfigureHttpsDefaults (azione<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Se si chiama ConfigureHttpsDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureHttpsDefaults(listenOptions =>
                {
                    // certificate is an X509Certificate2
                    listenOptions.ServerCertificate = certificate;
                });
            })
            .UseStartup<Startup>();
        });
}

Configure(IConfiguration)Configure(IConfiguration)

Crea un loader di configurazione per la configurazione di Kestrel che accetta un elemento IConfiguration come input.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. L'ambito della configurazione deve essere la sezione di configurazione per Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configura Kestrel per l'uso di HTTPS.Configure Kestrel to use HTTPS.

Estensioni ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps - Configura Kestrel per l'uso di HTTPS con il certificato predefinito.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Genera un'eccezione se non è stato configurato alcun certificato predefinito.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)

Parametri ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename è il percorso e il nome file di un file di certificato, relativo alla directory che contiene i file di contenuto dell'app.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password è la password richiesta per accedere ai dati del certificato X.509.password is the password required to access the X.509 certificate data.
  • configureOptions è un elemento Action per configurare HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Restituisce ListenOptions.Returns the ListenOptions.
  • storeName è l'archivio certificati da cui caricare il certificato.storeName is the certificate store from which to load the certificate.
  • subject è il nome dell'oggetto del certificato.subject is the subject name for the certificate.
  • allowInvalid indica se devono essere considerati i certificati non validi, come ad esempio i certificati autofirmati.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location è il percorso dell'archivio da cui caricare il certificato.location is the store location to load the certificate from.
  • serverCertificate è il certificato X.509.serverCertificate is the X.509 certificate.

Nell'ambiente di produzione, HTTPS deve essere configurato in modo esplicito.In production, HTTPS must be explicitly configured. Come minimo, è necessario specificare un certificato predefinito.At a minimum, a default certificate must be provided.

Configurazioni supportate descritte in seguito:Supported configurations described next:

  • Nessuna configurazioneNo configuration
  • Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration
  • Modificare le impostazioni predefinite nel codiceChange the defaults in code

Nessuna configurazioneNo configuration

Kestrel è in ascolto su http://localhost:5000 e https://localhost:5001 (se è disponibile un certificato predefinito).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration

CreateDefaultBuilder chiama Configure(context.Configuration.GetSection("Kestrel")) per impostazione predefinita per caricare la configurazione di Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. È disponibile per Kestrel uno schema di configurazione delle impostazioni delle app HTTPS predefinito.A default HTTPS app settings configuration schema is available for Kestrel. Configurare più endpoint, inclusi gli URL e i certificati da usare, da un file su disco o da un archivio certificati.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Nel file appsettings.json di esempio seguente:In the following appsettings.json example:

  • Impostare AllowInvalid su true per consentire l'uso di certificati non validi, come ad esempio i certificati autofirmati.Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Tutti gli endpoint HTTPS che non specificano un certificato (HttpsDefaultCert nell'esempio che segue) usano il certificato definito in Certificates > Default o il certificato di sviluppo.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>"
      }
    }
  }
}

Un'alternativa all'uso di Path e Password per qualsiasi nodo del certificato consiste nello specificare il certificato usando i campi dell'archivio certificati.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Ad esempio, il certificato specificato mediante Certificates > Default può essere specificato come: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>"
}

Note di schema:Schema notes:

  • I nomi degli endpoint non applicano la distinzione tra maiuscole e minuscole.Endpoints names are case-insensitive. Ad esempio, sono validi sia HTTPS che Https.For example, HTTPS and Https are valid.
  • Il parametro Url è obbligatorio per ogni endpoint.The Url parameter is required for each endpoint. Il formato per questo parametro è uguale a quello del parametro di configurazione di primo livello Urls, con la differenza che si limita a un singolo valore.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Questi endpoint sostituiscono quelli definiti nella configurazione di primo livello Urls, non vi si aggiungono.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Gli endpoint definiti nel codice tramite Listen si aggiungono agli endpoint definiti nella sezione di configurazione.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sezione Certificate è facoltativa.The Certificate section is optional. Se la sezione Certificate non è specificata, vengono usati i valori predefiniti definiti negli scenari precedenti.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se non è disponibile alcun valore predefinito, il server genera un'eccezione e non viene avviato.If no defaults are available, the server throws an exception and fails to start.
  • La sezione Certificate supporta sia i certificati PathPassword che i certificati SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • In questo modo è possibile definire un numero qualsiasi di endpoint, purché non provochino conflitti di porte.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}")) restituisce un oggetto KestrelConfigurationLoader con un metodo .Endpoint(string name, listenOptions => { }) che può essere usato per integrare le impostazioni dell'endpoint configurato: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 IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseKestrel((context, serverOptions) =>
            {
                serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
                    .Endpoint("HTTPS", listenOptions =>
                    {
                        listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
                    });
            });
        });

KestrelServerOptions.ConfigurationLoaderè possibile accedere direttamente a per continuare a scorrere sul caricatore esistente, ad esempio quello fornito da CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sezione di configurazione per ogni endpoint è disponibile sulle opzioni nel metodo Endpoint in modo che le impostazioni personalizzate possano essere lette.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • È possibile caricare più configurazioni chiamando ancora options.Configure(context.Configuration.GetSection("{SECTION}")) con un'altra sezione.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Viene usata solo l'ultima configurazione, a meno che Load sia stato chiamato esplicitamente in istanze precedenti.Only the last configuration is used, unless Load is explicitly called on prior instances. Il metapacchetto non chiama Load in modo che la sezione di configurazione predefinita venga sostituita.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader riflette la famiglia di API Listen da KestrelServerOptions all'overload di Endpoint, in modo che gli endpoint di codice e di configurazione possano essere configurati nella stessa posizione.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Questi overload non usano nomi e usano solo le impostazioni predefinite della configurazione.These overloads don't use names and only consume default settings from configuration.

Modificare le impostazioni predefinite nel codiceChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults possono essere usati per modificare le impostazioni predefinite per ListenOptions e HttpsConnectionAdapterOptions, inclusa l'esecuzione dell'override del certificato predefinito specificato nello scenario precedente.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 e ConfigureHttpsDefaults devono essere chiamati prima che venga configurato qualsiasi endpoint.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.ConfigureEndpointDefaults(listenOptions =>
                {
                    // Configure endpoint defaults
                });

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

Supporto kestrel per SNIKestrel support for SNI

L'Indicazione nome server (SNI) può essere usata per ospitare più domini sulla stessa porta e indirizzo IP.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Perché SNI funzioni è necessario che il client invii al server il nome host per la sessione protetta durante l'handshake TLS in modo che il server possa specificare il certificato corretto.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. Il client usa il certificato specificato per la comunicazione crittografata con il server durante la sessione protetta che segue l'handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel supporta SNI tramite il callback ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. Il callback viene richiamato una volta per ogni connessione per consentire all'app di controllare il nome host e selezionare il certificato appropriato.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Il supporto SNI richiede:SNI support requires:

  • In esecuzione su Framework netcoreapp2.1 di destinazione o versione successiva.Running on target framework netcoreapp2.1 or later. In net461 o versioni successive, il callback viene richiamato name , ma nullè sempre.On net461 or later, the callback is invoked but the name is always null. L'elemento name è null anche se il client non specifica il parametro del nome host nell'handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Esecuzione di tutti i siti Web nella stessa istanza di Kestrel.All websites run on the same Kestrel instance. Kestrel supporta la condivisione di un indirizzo IP e di una porta tra più istanze solo con un proxy inverso.Kestrel doesn't support sharing an IP address and port across multiple instances without a reverse proxy.
public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            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;
                        };
                    });
                });
            })
            .UseStartup<Startup>();
        });

Associazione a un socket TCPBind to a TCP socket

Il metodo Listen esegue l'associazione a un socket TCP e un'espressione lambda per le opzioni consente di configurare un certificato 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>();
        });

L'esempio configura HTTPS per un endpoint con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Usare la stessa API per configurare altre impostazioni di Kestrel per endpoint specifici.Use the same API to configure other Kestrel settings for specific endpoints.

In Windows è possibile creare certificati autofirmati con il cmdlet di PowerShell New-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Per un esempio non supportato, vedere UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

In macOS, Linux e Windows, i certificati possono essere creati con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associazione a un socket UnixBind to a Unix socket

Impostare l'ascolto su un socket Unix con ListenUnixSocket per migliorare le prestazioni con Nginx, come visualizzato nell'esempio seguente: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");
        });
})

Porta 0Port 0

Quando si specifica il numero di porta 0, Kestrel esegue l'associazione dinamica a una porta disponibile.When the port number 0 is specified, Kestrel dynamically binds to an available port. L'esempio seguente indica come determinare la porta alla quale Kestrel ha eseguito l'associazione in fase di esecuzione: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>");
    });
}

Quando si esegue l'app, l'output della finestra della console indica la porta dinamica in cui l'app può essere raggiunta: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

LimitazioniLimitations

Configurare gli endpoint con i metodi seguenti:Configure endpoints with the following approaches:

  • UseUrls
  • L'argomento della riga di comando --urls--urls command-line argument
  • La chiave di configurazione dell'host urlsurls host configuration key
  • La variabile di ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Questi metodi sono utili se si vuole che il codice funzioni con server diversi da Kestrel.These methods are useful for making code work with servers other than Kestrel. Tenere presenti, tuttavia, le limitazioni seguenti:However, be aware of the following limitations:

  • HTTPS non può essere usato con questi approcci, a meno che non venga specificato un certificato predefinito nella configurazione dell'endpoint HTTPS (ad esempio, usando la configurazione KestrelServerOptions o un file di configurazione come illustrato in precedenza in questo argomento).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).
  • Quando sia l'approccio Listen che l'approccio UseUrls vengono usati contemporaneamente, gli endpoint Listen eseguono l'override degli endpoint UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configurazione dell'endpoint IISIIS endpoint configuration

Quando si usa IIS, le associazioni di URL per le associazioni di override di IIS vengono impostate mediante Listen o UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Per altre informazioni, vedere l'articolo Introduzione al modulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

La proprietà Protocols stabilisce i protocolli HTTP (HttpProtocols) abilitati in un endpoint di connessione o per il server.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Assegnare un valore alla proprietà Protocols dall'enumerazione HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valore di enumerazione HttpProtocolsHttpProtocols enum value Protocollo di connessione consentitoConnection protocol permitted
Http1 Solo HTTP/1.1.HTTP/1.1 only. Può essere usato con o senza TLS.Can be used with or without TLS.
Http2 Solo HTTP/2.HTTP/2 only. Può essere usato senza TLS solo se il client supporta una modalità di conoscenza pregressa.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 e HTTP/2.HTTP/1.1 and HTTP/2. HTTP/2 richiede che il client selezioni HTTP/2 nell'handshake TLS (Application-Layer Protocol negotiation) ALPN in caso contrario, il valore predefinito per la connessione è 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.

Il valore ListenOptions.Protocols predefinito per qualsiasi endpoint è HttpProtocols.Http1AndHttp2.The default ListenOptions.Protocols value for any endpoint is HttpProtocols.Http1AndHttp2.

Restrizioni relative a TLS per HTTP/2:TLS restrictions for HTTP/2:

  • TLS versione 1.2 o successivaTLS version 1.2 or later
  • Rinegoziazione disabilitataRenegotiation disabled
  • Compressione disabilitataCompression disabled
  • Dimensioni minime per lo scambio di chiavi temporanee:Minimum ephemeral key exchange sizes:
    • Diffie-Hellman a curva ellittica (ECDH) [RFC4492] – 224 bit (minimo)Elliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • Diffie-Hellman a campo finito (DHE) [TLS12] – 2048 bit (minimo)Finite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Pacchetto di crittografia consentitoCipher suite not blacklisted

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] con curva ellittica P-256 [FIPS186] è supportato per impostazione predefinita.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Nell'esempio seguente sono consentite connessioni HTTP/1.1 e HTTP/2 sulla porta 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Le connessioni sono protette da TLS con un certificato incluso:Connections are secured by TLS with a supplied certificate:

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

Usare facoltativamente il middleware di connessione per filtrare gli handshake TLS in base alla connessione per le crittografie specifiche:Optionally use Connection Middleware to filter TLS handshakes on a per-connection basis for specific ciphers:

// using System.Net;
// using Microsoft.AspNetCore.Connections;

.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseConnectionHandler<TlsFilterConnectionHandler>();
    });
});
using System;
using System.Buffers;
using System.Security.Authentication;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Connections;
using Microsoft.AspNetCore.Connections.Features;

public class TlsFilterConnectionHandler : ConnectionHandler
{
    public override async Task OnConnectedAsync(ConnectionContext connection)
    {
        var tlsFeature = connection.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.
        //
        // 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);
        }

        while (true)
        {
            var result = await connection.Transport.Input.ReadAsync();
            var buffer = result.Buffer;

            if (!buffer.IsEmpty)
            {
                await connection.Transport.Output.WriteAsync(buffer.ToArray());
            }
            else if (result.IsCompleted)
            {
                break;
            }

            connection.Transport.Input.AdvanceTo(buffer.End);
        }
    }
}

Impostare il protocollo dalla configurazioneSet the protocol from configuration

CreateDefaultBuilder chiama serverOptions.Configure(context.Configuration.GetSection("Kestrel")) per impostazione predefinita per caricare la configurazione di Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

L'esempio appSettings. JSON seguente stabilisce http/1.1 come protocollo di connessione predefinito per tutti gli endpoint:The following appsettings.json example establishes HTTP/1.1 as the default connection protocol for all endpoints:

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

Nell'esempio appSettings. JSON seguente viene stabilito il protocollo di connessione HTTP/1.1 per un endpoint specifico: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"
      }
    }
  }
}

I protocolli specificati nei valori di override del codice sono impostati dalla configurazione.Protocols specified in code override values set by configuration.

Configurazione del trasportoTransport configuration

Per i progetti che richiedono l'utilizzo di libuvUseLibuv():For projects that require the use of Libuv (UseLibuv):

  • Aggiungere una dipendenza per il pacchetto Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al file di progetto dell'app: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 ChiamareIWebHostBuildersu: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>();
                 });
    }
    

Prefissi URLURL prefixes

Se si usa UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls o la variabile di ambiente ASPNETCORE_URLS, i prefissi URL possono avere uno dei formati seguenti.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.

Sono validi solo i prefissi URL HTTP.Only HTTP URL prefixes are valid. Kestrel non supporta HTTPS quando la configurazione delle associazioni URL viene eseguita con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Indirizzo IPv4 con numero di portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 è un caso speciale che esegue l'associazione a tutti gli indirizzi IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Indirizzo IPv6 con numero di portaIPv6 address with port number

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

    [::] è l'equivalente IPv6 di 0.0.0.0 per IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome host con numero di portaHost name with port number

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

    I nomi host, * e + non sono casi particolari.Host names, *, and +, aren't special. Tutto ciò che non è riconosciuto come un indirizzo IP o un elemento localhost valido esegue l'associazione a tutti gli IP IPv4 e IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Per associare nomi host diversi ad app ASP.NET Core diverse sulla stessa porta, usare HTTP.sys o un server proxy inverso come IIS, Nginx o 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.

    Avviso

    Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome host localhost con numero di porta o IP di loopback con numero di portaHost localhost name with port number or loopback IP with port number

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

    Se è specificato localhost, Kestrel tenta l'associazione alle interfacce di loopback sia IPv4 che IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se la porta richiesta è in uso da parte di un altro servizio in una delle due interfacce di loopback, Kestrel non viene avviato.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se una delle due interfacce di loopback non è disponibile per qualsiasi altro motivo (in genere perché IPv6 non è supportato), Kestrel registra un avviso.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtro hostHost filtering

Mentre supporta la configurazione in base ai prefissi, ad esempio http://example.com:5000, Kestrel ignora quasi sempre il nome host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. L'host localhost è un caso speciale usato per l'associazione agli indirizzi di loopback.Host localhost is a special case used for binding to loopback addresses. Qualsiasi host che non sia un indirizzo IP esplicito esegue l'associazione a tutti gli indirizzi IP pubblici.Any host other than an explicit IP address binds to all public IP addresses. Le intestazioni Host non vengono convalidate.Host headers aren't validated.

Come soluzione alternativa, usare il middleware di filtro host.As a workaround, use Host Filtering Middleware. Il middleware di filtro host viene fornito dal pacchetto Microsoft. AspNetCore. HostFiltering , fornito in modo implicito per le app ASP.NET Core.Host Filtering Middleware is provided by the Microsoft.AspNetCore.HostFiltering package, which is implicitly provided for ASP.NET Core apps. Il middleware viene aggiunto da CreateDefaultBuilder, che chiama 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>();
}

Per impostazione predefinita, il middleware di filtro host è disabilitato per impostazione predefinita.Host Filtering Middleware is disabled by default. Per abilitare il middleware, definire una chiave AllowedHosts in appsettings.json/appsettings.<NomeAmbiente>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Il valore è un elenco con valori delimitati da punto e virgola di nomi host senza numeri di porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Il middleware delle intestazioni inoltrate include anche un'opzione AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Il middleware di intestazioni inoltrate e il middleware di filtro host hanno funzionalità simili per diversi scenari.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. L'impostazione di AllowedHosts con il middleware delle intestazioni inoltrate è appropriato se l'intestazione Host non viene mantenuta durante l'inoltro delle richieste con un server proxy inverso o il bilanciamento del carico.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. L'impostazione di AllowedHosts con il middleware del filtro host è appropriata se si usa Kestrel come server perimetrale rivolto al pubblico o se l'intestazione Host viene inoltrata direttamente.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.

Per altre informazioni sul middleware delle intestazioni inoltrate, vedere Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.For more information on Forwarded Headers Middleware, see Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.

Kestrel è un server Web per ASP.NET Core multipiattaforma.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel è il server Web incluso per impostazione predefinita nei modelli di progetto di ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel supporta gli scenari seguenti:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Aggiornamento opaco usato per abilitare WebSocketOpaque upgrade used to enable WebSockets
  • Socket Unix ad alte prestazioni dietro NginxUnix sockets for high performance behind Nginx
  • HTTP/2 (tranne che in macOS†)HTTP/2 (except on macOS†)

†HTTP/2 verrà supportato in macOS in una versione futura.†HTTP/2 will be supported on macOS in a future release.

Kestrel è supportato in tutte le piattaforme e le versioni supportate da .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Supporto per HTTP/2HTTP/2 support

HTTP/2 è disponibile per le app ASP.NET Core se vengono soddisfatti i requisiti di base seguenti:HTTP/2 is available for ASP.NET Core apps if the following base requirements are met:

  • Sistema operativo†Operating system†
    • Windows Server 2016/Windows 10 o versioni successive‡Windows Server 2016/Windows 10 or later‡
    • Linux con OpenSSL 1.0.2 o versioni successive (ad esempio, Ubuntu 16.04 o versioni successive)Linux with OpenSSL 1.0.2 or later (for example, Ubuntu 16.04 or later)
  • Framework di destinazione: .NET Core 2.2 o versioni successiveTarget framework: .NET Core 2.2 or later
  • Connessione ALPN (Application-Layer Protocol Negotiation)Application-Layer Protocol Negotiation (ALPN) connection
  • Connessione TLS 1.2 o successivaTLS 1.2 or later connection

†HTTP/2 verrà supportato in macOS in una versione futura.†HTTP/2 will be supported on macOS in a future release. ‡Kestrel ha un supporto limitato per HTTP/2 in Windows Server 2012 R2 e Windows 8.1.‡Kestrel has limited support for HTTP/2 on Windows Server 2012 R2 and Windows 8.1. Il supporto è limitato perché l'elenco di suite di crittografia TLS supportate disponibili in questi sistemi operativi è limitato.Support is limited because the list of supported TLS cipher suites available on these operating systems is limited. Un certificato generato con un algoritmo ECDSA potrebbe essere necessario per proteggere le connessioni TLS.A certificate generated using an Elliptic Curve Digital Signature Algorithm (ECDSA) may be required to secure TLS connections.

Se viene stabilita una connessione HTTP/2, HttpRequest.Protocol corrisponde a HTTP/2.If an HTTP/2 connection is established, HttpRequest.Protocol reports HTTP/2.

HTTP/2 è disabilitato per impostazione predefinita.HTTP/2 is disabled by default. Per altre informazioni sulla configurazione, vedere le sezioni Opzioni Kestrel e ListenOptions.Protocols.For more information on configuration, see the Kestrel options and ListenOptions.Protocols sections.

Quando usare Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

È possibile usare Kestrel da solo o in combinazione con un server proxy inverso, ad esempio Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Il server proxy inverso riceve le richieste HTTP dalla rete e le inoltra a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usato come server Web perimetrale (esposto a Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel comunica direttamente con Internet senza un server proxy inverso

Kestrel usato in una configurazione proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel comunica indirettamente con Internet attraverso un server proxy inverso, ad esempio IIS, Nginx o Apache

La configurazione, con o senza un server proxy inverso, è una configurazione di hosting supportata.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Se viene utilizzato come server perimetrale in assenza di un server proxy inverso, Kestrel non supporta la condivisione tra più processi dell'IP e della porta.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando è configurato per restare in ascolto su una porta, Kestrel gestisce tutto il traffico per tale porta indipendentemente dalle intestazioni Host delle richieste.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Un proxy inverso che può condividere le porte può eseguire l'inoltro delle richieste a Kestrel su un unico IP e un'unica porta.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Anche se la presenza di un server proxy inverso non è necessaria, può risultare utile per i motivi seguenti.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso:A reverse proxy:

  • Può limitare l'area della superficie di attacco pubblica esposta delle app ospitate.Can limit the exposed public surface area of the apps that it hosts.
  • Offre un livello aggiuntivo di configurazione e protezione.Provide an additional layer of configuration and defense.
  • Potrebbe offrire un'integrazione migliore con l'infrastruttura esistente.Might integrate better with existing infrastructure.
  • Semplifica il bilanciamento del carico e la configurazione di comunicazioni protette (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solo il server proxy inverso richiede un certificato X. 509 e il server è in grado di comunicare con i server dell'app nella rete interna tramite HTTP normale.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.

Avviso

Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

Come usare Kestrel nelle app ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Il pacchetto Microsoft. AspNetCore. Server. gheppio è incluso nel metapacchetto Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

I modelli di progetto ASP.NET Core usano Kestrel per impostazione predefinita.ASP.NET Core project templates use Kestrel by default. In Program.cs il codice del modello chiama CreateDefaultBuilder, che chiama UseKestrel in background.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>();

Per fornire una configurazione aggiuntiva dopo la chiamata di CreateDefaultBuilder, usare 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
        });

Se l'app non chiama CreateDefaultBuilder per configurare l'host, chiamare UseKestrel prima di chiamare 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, serverOptions) =>
        {
            // Set properties and call methods on serverOptions
        })
        .Build();

    host.Run();
}

Opzioni KestrelKestrel options

Il server Web Kestrel dispone di opzioni di configurazione dei vincoli che risultano particolarmente utili nelle distribuzioni con connessione Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Impostare i vincoli per la proprietà Limits della classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La proprietà Limits contiene un'istanza della classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Negli esempi seguenti viene usato lo spazio dei nomi Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Timeout keep-aliveKeep-alive timeout

KeepAliveTimeout

Ottiene o imposta il timeout keep-alive.Gets or sets the keep-alive timeout. Il valore predefinito è 2 minuti.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);
});

Numero massimo di connessioni clientMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

È possibile impostare il numero massimo di connessioni TCP aperte simultaneamente per l'intera app con il codice seguente:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

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

È previsto un limite separato per le connessioni che sono state aggiornate da HTTP o HTTPS a un altro protocollo (ad esempio su una richiesta 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). Dopo l'aggiornamento di una connessione, questa non viene conteggiata per il limite MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

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

Per impostazione predefinita, il numero massimo di connessioni è illimitato (null).The maximum number of connections is unlimited (null) by default.

Dimensione massima del corpo della richiestaMaximum request body size

MaxRequestBodySize

La dimensione massima predefinita del corpo della richiesta è pari a 30.000.000 di byte, equivalenti a circa 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Il metodo consigliato per ignorare il limite in un'app ASP.NET Core MVC è l'uso dell'attributo RequestSizeLimitAttribute in un metodo di azione: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()

L'esempio seguente illustra come configurare il vincolo per l'app in ogni richiesta: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);
});

Eseguire l'override dell'impostazione per una richiesta specifica nel middleware: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));
    }

Viene generata un'eccezione se l'app configura il limite per una richiesta dopo che l'app ha iniziato a leggere la richiesta.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Una proprietà IsReadOnly indica se la proprietà MaxRequestBodySize è in stato di sola lettura e pertanto è troppo tardi per configurare il limite.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.

Quando un'app viene eseguita out-of-process dietro il modulo ASP.NET Core, il limite della dimensione del corpo della richiesta di Kestrel è disabilitato perché viene già impostato da 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.

Velocità minima dei dati del corpo della richiestaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel controlla ogni secondo se i dati arrivano alla velocità in byte al secondo specificata.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se la velocità scende sotto il valore minimo, la connessione raggiunge il timeout. Il periodo di tolleranza è la quantità di tempo che Kestrel concede al client per aumentare la velocità di trasmissione fino al valore minimo. Durante tale periodo la velocità non viene rilevata.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. Il periodo di prova consente di evitare l'interruzione di connessioni che inizialmente inviano i dati a velocità ridotta a causa dell'avvio lento del protocollo TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocità minima predefinita è di 240 byte al secondo, con un periodo di tolleranza di 5 secondi.The default minimum rate is 240 bytes/second with a 5 second grace period.

Anche per la risposta è prevista una velocità minima.A minimum rate also applies to the response. Il codice per impostare il limite della richiesta e della risposta è identico e varia solo per RequestBody o Response nei nomi di proprietà e di interfaccia.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.

L'esempio seguente visualizza come configurare la velocità minima dei dati in 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);
});

Ignorare i limiti di velocità minima per ogni richiesta nel middleware: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));
    }

Nessuna delle due funzionalità relative alla velocità, a cui si fa riferimento nell'esempio precedente, è presente in HttpContext.Features per le richieste HTTP/2 perché la modifica dei limiti di velocità per ogni richiesta non è supportata per HTTP/2 a causa del supporto del protocollo per il multiplexing delle richieste.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. I limiti di velocità a livello di server configurati tramite KestrelServerOptions.Limits vengono tuttavia applicati alle connessioni HTTP/1.x e HTTP/2.Server-wide rate limits configured via KestrelServerOptions.Limits still apply to both HTTP/1.x and HTTP/2 connections.

Timeout delle intestazioni delle richiesteRequest headers timeout

RequestHeadersTimeout

Ottiene o imposta la quantità massima di tempo che il server dedica alla ricezione delle intestazioni delle richieste.Gets or sets the maximum amount of time the server spends receiving request headers. Il valore predefinito è 30 secondi.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);
});

Numero massimo di flussi per connessioneMaximum streams per connection

Http2.MaxStreamsPerConnection limita il numero di flussi di richieste simultanee per ogni connessione HTTP/2.Http2.MaxStreamsPerConnection limits the number of concurrent request streams per HTTP/2 connection. I flussi in eccesso vengono rifiutati.Excess streams are refused.

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

Il valore predefinito è 100.The default value is 100.

Dimensioni della tabella delle intestazioniHeader table size

Il decodificatore HPACK decomprime le intestazioni HTTP per le connessioni HTTP/2.The HPACK decoder decompresses HTTP headers for HTTP/2 connections. Http2.HeaderTableSize limita le dimensioni della tabella di compressione delle intestazioni usata dal decodificatore HPACK.Http2.HeaderTableSize limits the size of the header compression table that the HPACK decoder uses. Il valore viene specificato in ottetti e deve essere maggiore di zero (0).The value is provided in octets and must be greater than zero (0).

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

Il valore predefinito è 4096.The default value is 4096.

Dimensione massima del frameMaximum frame size

Http2.MaxFrameSize indica le dimensioni massime del payload del frame di connessione HTTP/2 da ricevere.Http2.MaxFrameSize indicates the maximum size of the HTTP/2 connection frame payload to receive. Il valore viene specificato in ottetti e deve essere compreso tra 2^14 (16.384) e 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;
        });

Il valore predefinito è 2^14 (16.384).The default value is 2^14 (16,384).

Dimensioni massime dell'intestazione della richiestaMaximum request header size

Http2.MaxRequestHeaderFieldSize indica le dimensioni massime consentite in ottetti di valori di intestazione di richiesta.Http2.MaxRequestHeaderFieldSize indicates the maximum allowed size in octets of request header values. Questo limite si applica insieme sia al nome che al valore nelle rappresentazioni compresse e non compresse.This limit applies to both name and value together in their compressed and uncompressed representations. Il valore deve essere maggiore di zero (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;
        });

Il valore predefinito è 8.192.The default value is 8,192.

Dimensioni della finestra di connessione inizialiInitial connection window size

Http2.InitialConnectionWindowSize indica il numero massimo di byte di dati del corpo della richiesta che il server memorizza nel buffer in una volta, aggregati in tutte le richieste (flussi), per ogni connessione.Http2.InitialConnectionWindowSize indicates the maximum request body data in bytes the server buffers at one time aggregated across all requests (streams) per connection. Le richieste sono anche limitate da Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. Il valore deve essere maggiore di o uguale a 65.535 e minore di 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.InitialConnectionWindowSize = 131072;
        });

Il valore predefinito è 128 KB (131.072).The default value is 128 KB (131,072).

Dimensioni della finestra di flusso inizialiInitial stream window size

Http2.InitialStreamWindowSize indica il numero massimo di byte di dati del corpo della richiesta che il server memorizza nel buffer in una volta per ogni richiesta (flusso).Http2.InitialStreamWindowSize indicates the maximum request body data in bytes the server buffers at one time per request (stream). Le richieste sono anche limitate da Http2.InitialStreamWindowSize.Requests are also limited by Http2.InitialStreamWindowSize. Il valore deve essere maggiore di o uguale a 65.535 e minore di 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;
        });

Il valore predefinito è 96 KB (98.304).The default value is 96 KB (98,304).

I/O sincronoSynchronous IO

AllowSynchronousIO controlla se l'I/O sincrono è consentito per la richiesta e la risposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. Il valore predefinito è true.The default value is true.

Avviso

Un numero elevato di operazioni di I/O sincrone bloccanti può portare alla scadenza del pool di thread, a causa della quale l'app smette di rispondere.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Abilitare solo AllowSynchronousIO quando si usa una libreria che non supporta l'I/O asincrono.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

L'esempio seguente abilita l'I/O sincrono:The following example enables synchronous IO:

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

Per informazioni su altre opzioni e limiti di Kestrel, vedere:For information about other Kestrel options and limits, see:

Configurazione dell'endpointEndpoint configuration

Per impostazione predefinita, ASP.NET Core è associato a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando è presente un certificato di sviluppo locale)https://localhost:5001 (when a local development certificate is present)

Specificare gli URL usando gli elementi seguenti:Specify URLs using the:

  • La variabile di ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • L'argomento della riga di comando --urls.--urls command-line argument.
  • La chiave di configurazione dell'host urls.urls host configuration key.
  • Il metodo di estensione UseUrls.UseUrls extension method.

Il valore specificato usando i metodi seguenti può essere uno o più endpoint HTTP e HTTPS (HTTPS se è disponibile un certificato predefinito).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configurare il valore come un elenco delimitato da punto e virgola (ad esempio, "Urls": "http://localhost:8000; http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Per altre informazioni su questi approcci, vedere URL del server e Override della configurazione.For more information on these approaches, see Server URLs and Override configuration.

Viene creato un certificato di sviluppo nei casi seguenti:A development certificate is created:

Alcuni browser richiedono la concessione di autorizzazioni esplicite per considerare attendibile il certificato di sviluppo locale.Some browsers require granting explicit permission to trust the local development certificate.

I modelli di progetto consentono di configurare le app per l'esecuzione su HTTPS per impostazione predefinita e includono il reindirizzamento HTTPS e il supporto HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chiamare i metodi Listen oppure ListenUnixSocket su KestrelServerOptions per configurare le porte e i prefissi URL per Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

Anche UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls e la variabile di ambiente ASPNETCORE_URLS funzionano, ma con le limitazioni indicate più avanti nella sezione (deve essere disponibile un certificato predefinito per la configurazione dell'endopoint 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).

KestrelServerOptionsconfigurazioneKestrelServerOptions configuration:

ConfigureEndpointDefaults (azione<ListenOptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint specificato.Specifies a configuration Action to run for each specified endpoint. Se si chiama ConfigureEndpointDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

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

ConfigureHttpsDefaults (azione<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Se si chiama ConfigureHttpsDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

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)

Crea un loader di configurazione per la configurazione di Kestrel che accetta un elemento IConfiguration come input.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. L'ambito della configurazione deve essere la sezione di configurazione per Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configura Kestrel per l'uso di HTTPS.Configure Kestrel to use HTTPS.

Estensioni ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps - Configura Kestrel per l'uso di HTTPS con il certificato predefinito.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Genera un'eccezione se non è stato configurato alcun certificato predefinito.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)

Parametri ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename è il percorso e il nome file di un file di certificato, relativo alla directory che contiene i file di contenuto dell'app.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password è la password richiesta per accedere ai dati del certificato X.509.password is the password required to access the X.509 certificate data.
  • configureOptions è un elemento Action per configurare HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Restituisce ListenOptions.Returns the ListenOptions.
  • storeName è l'archivio certificati da cui caricare il certificato.storeName is the certificate store from which to load the certificate.
  • subject è il nome dell'oggetto del certificato.subject is the subject name for the certificate.
  • allowInvalid indica se devono essere considerati i certificati non validi, come ad esempio i certificati autofirmati.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location è il percorso dell'archivio da cui caricare il certificato.location is the store location to load the certificate from.
  • serverCertificate è il certificato X.509.serverCertificate is the X.509 certificate.

Nell'ambiente di produzione, HTTPS deve essere configurato in modo esplicito.In production, HTTPS must be explicitly configured. Come minimo, è necessario specificare un certificato predefinito.At a minimum, a default certificate must be provided.

Configurazioni supportate descritte in seguito:Supported configurations described next:

  • Nessuna configurazioneNo configuration
  • Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration
  • Modificare le impostazioni predefinite nel codiceChange the defaults in code

Nessuna configurazioneNo configuration

Kestrel è in ascolto su http://localhost:5000 e https://localhost:5001 (se è disponibile un certificato predefinito).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration

CreateDefaultBuilder chiama Configure(context.Configuration.GetSection("Kestrel")) per impostazione predefinita per caricare la configurazione di Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. È disponibile per Kestrel uno schema di configurazione delle impostazioni delle app HTTPS predefinito.A default HTTPS app settings configuration schema is available for Kestrel. Configurare più endpoint, inclusi gli URL e i certificati da usare, da un file su disco o da un archivio certificati.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Nel file appsettings.json di esempio seguente:In the following appsettings.json example:

  • Impostare AllowInvalid su true per consentire l'uso di certificati non validi, come ad esempio i certificati autofirmati.Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Tutti gli endpoint HTTPS che non specificano un certificato (HttpsDefaultCert nell'esempio che segue) usano il certificato definito in Certificates > Default o il certificato di sviluppo.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>"
      }
    }
  }
}

Un'alternativa all'uso di Path e Password per qualsiasi nodo del certificato consiste nello specificare il certificato usando i campi dell'archivio certificati.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Ad esempio, il certificato specificato mediante Certificates > Default può essere specificato come: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>"
}

Note di schema:Schema notes:

  • I nomi degli endpoint non applicano la distinzione tra maiuscole e minuscole.Endpoints names are case-insensitive. Ad esempio, sono validi sia HTTPS che Https.For example, HTTPS and Https are valid.
  • Il parametro Url è obbligatorio per ogni endpoint.The Url parameter is required for each endpoint. Il formato per questo parametro è uguale a quello del parametro di configurazione di primo livello Urls, con la differenza che si limita a un singolo valore.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Questi endpoint sostituiscono quelli definiti nella configurazione di primo livello Urls, non vi si aggiungono.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Gli endpoint definiti nel codice tramite Listen si aggiungono agli endpoint definiti nella sezione di configurazione.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sezione Certificate è facoltativa.The Certificate section is optional. Se la sezione Certificate non è specificata, vengono usati i valori predefiniti definiti negli scenari precedenti.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se non è disponibile alcun valore predefinito, il server genera un'eccezione e non viene avviato.If no defaults are available, the server throws an exception and fails to start.
  • La sezione Certificate supporta sia i certificati PathPassword che i certificati SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • In questo modo è possibile definire un numero qualsiasi di endpoint, purché non provochino conflitti di porte.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}")) restituisce un oggetto KestrelConfigurationLoader con un metodo .Endpoint(string name, listenOptions => { }) che può essere usato per integrare le impostazioni dell'endpoint configurato: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;
                });
        });

KestrelServerOptions.ConfigurationLoaderè possibile accedere direttamente a per continuare a scorrere sul caricatore esistente, ad esempio quello fornito da CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sezione di configurazione per ogni endpoint è disponibile sulle opzioni nel metodo Endpoint in modo che le impostazioni personalizzate possano essere lette.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • È possibile caricare più configurazioni chiamando ancora options.Configure(context.Configuration.GetSection("{SECTION}")) con un'altra sezione.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Viene usata solo l'ultima configurazione, a meno che Load sia stato chiamato esplicitamente in istanze precedenti.Only the last configuration is used, unless Load is explicitly called on prior instances. Il metapacchetto non chiama Load in modo che la sezione di configurazione predefinita venga sostituita.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader riflette la famiglia di API Listen da KestrelServerOptions all'overload di Endpoint, in modo che gli endpoint di codice e di configurazione possano essere configurati nella stessa posizione.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Questi overload non usano nomi e usano solo le impostazioni predefinite della configurazione.These overloads don't use names and only consume default settings from configuration.

Modificare le impostazioni predefinite nel codiceChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults possono essere usati per modificare le impostazioni predefinite per ListenOptions e HttpsConnectionAdapterOptions, inclusa l'esecuzione dell'override del certificato predefinito specificato nello scenario precedente.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 e ConfigureHttpsDefaults devono essere chiamati prima che venga configurato qualsiasi endpoint.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

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

Supporto kestrel per SNIKestrel support for SNI

L'Indicazione nome server (SNI) può essere usata per ospitare più domini sulla stessa porta e indirizzo IP.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Perché SNI funzioni è necessario che il client invii al server il nome host per la sessione protetta durante l'handshake TLS in modo che il server possa specificare il certificato corretto.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. Il client usa il certificato specificato per la comunicazione crittografata con il server durante la sessione protetta che segue l'handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel supporta SNI tramite il callback ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. Il callback viene richiamato una volta per ogni connessione per consentire all'app di controllare il nome host e selezionare il certificato appropriato.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Il supporto SNI richiede:SNI support requires:

  • In esecuzione su Framework netcoreapp2.1 di destinazione o versione successiva.Running on target framework netcoreapp2.1 or later. In net461 o versioni successive, il callback viene richiamato name , ma nullè sempre.On net461 or later, the callback is invoked but the name is always null. L'elemento name è null anche se il client non specifica il parametro del nome host nell'handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Esecuzione di tutti i siti Web nella stessa istanza di Kestrel.All websites run on the same Kestrel instance. Kestrel supporta la condivisione di un indirizzo IP e di una porta tra più istanze solo con un proxy inverso.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;
                    };
                });
            });
        });

Associazione a un socket TCPBind to a TCP socket

Il metodo Listen esegue l'associazione a un socket TCP e un'espressione lambda per le opzioni consente di configurare un certificato 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");
            });
        });

L'esempio configura HTTPS per un endpoint con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Usare la stessa API per configurare altre impostazioni di Kestrel per endpoint specifici.Use the same API to configure other Kestrel settings for specific endpoints.

In Windows è possibile creare certificati autofirmati con il cmdlet di PowerShell New-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Per un esempio non supportato, vedere UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

In macOS, Linux e Windows, i certificati possono essere creati con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associazione a un socket UnixBind to a Unix socket

Impostare l'ascolto su un socket Unix con ListenUnixSocket per migliorare le prestazioni con Nginx, come visualizzato nell'esempio seguente:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

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

Porta 0Port 0

Quando si specifica il numero di porta 0, Kestrel esegue l'associazione dinamica a una porta disponibile.When the port number 0 is specified, Kestrel dynamically binds to an available port. L'esempio seguente indica come determinare la porta alla quale Kestrel ha eseguito l'associazione in fase di esecuzione: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>");
    });
}

Quando si esegue l'app, l'output della finestra della console indica la porta dinamica in cui l'app può essere raggiunta: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

LimitazioniLimitations

Configurare gli endpoint con i metodi seguenti:Configure endpoints with the following approaches:

  • UseUrls
  • L'argomento della riga di comando --urls--urls command-line argument
  • La chiave di configurazione dell'host urlsurls host configuration key
  • La variabile di ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Questi metodi sono utili se si vuole che il codice funzioni con server diversi da Kestrel.These methods are useful for making code work with servers other than Kestrel. Tenere presenti, tuttavia, le limitazioni seguenti:However, be aware of the following limitations:

  • HTTPS non può essere usato con questi approcci, a meno che non venga specificato un certificato predefinito nella configurazione dell'endpoint HTTPS (ad esempio, usando la configurazione KestrelServerOptions o un file di configurazione come illustrato in precedenza in questo argomento).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).
  • Quando sia l'approccio Listen che l'approccio UseUrls vengono usati contemporaneamente, gli endpoint Listen eseguono l'override degli endpoint UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configurazione dell'endpoint IISIIS endpoint configuration

Quando si usa IIS, le associazioni di URL per le associazioni di override di IIS vengono impostate mediante Listen o UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Per altre informazioni, vedere l'articolo Introduzione al modulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

ListenOptions.ProtocolsListenOptions.Protocols

La proprietà Protocols stabilisce i protocolli HTTP (HttpProtocols) abilitati in un endpoint di connessione o per il server.The Protocols property establishes the HTTP protocols (HttpProtocols) enabled on a connection endpoint or for the server. Assegnare un valore alla proprietà Protocols dall'enumerazione HttpProtocols.Assign a value to the Protocols property from the HttpProtocols enum.

Valore di enumerazione HttpProtocolsHttpProtocols enum value Protocollo di connessione consentitoConnection protocol permitted
Http1 Solo HTTP/1.1.HTTP/1.1 only. Può essere usato con o senza TLS.Can be used with or without TLS.
Http2 Solo HTTP/2.HTTP/2 only. Può essere usato senza TLS solo se il client supporta una modalità di conoscenza pregressa.May be used without TLS only if the client supports a Prior Knowledge mode.
Http1AndHttp2 HTTP/1.1 e HTTP/2.HTTP/1.1 and HTTP/2. HTTP/2 richiede una connessione TLS e ALPN (Application-Layer Protocol negotiation) ; in caso contrario, il valore predefinito per la connessione è HTTP/1.1.HTTP/2 requires a TLS and Application-Layer Protocol Negotiation (ALPN) connection; otherwise, the connection defaults to HTTP/1.1.

Il protocollo predefinito è HTTP/1.1.The default protocol is HTTP/1.1.

Restrizioni relative a TLS per HTTP/2:TLS restrictions for HTTP/2:

  • TLS versione 1.2 o successivaTLS version 1.2 or later
  • Rinegoziazione disabilitataRenegotiation disabled
  • Compressione disabilitataCompression disabled
  • Dimensioni minime per lo scambio di chiavi temporanee:Minimum ephemeral key exchange sizes:
    • Diffie-Hellman a curva ellittica (ECDH) [RFC4492] – 224 bit (minimo)Elliptic curve Diffie-Hellman (ECDHE) [RFC4492] – 224 bits minimum
    • Diffie-Hellman a campo finito (DHE) [TLS12] – 2048 bit (minimo)Finite field Diffie-Hellman (DHE) [TLS12] – 2048 bits minimum
  • Pacchetto di crittografia consentitoCipher suite not blacklisted

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] con curva ellittica P-256 [FIPS186] è supportato per impostazione predefinita.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186] is supported by default.

Nell'esempio seguente sono consentite connessioni HTTP/1.1 e HTTP/2 sulla porta 8000.The following example permits HTTP/1.1 and HTTP/2 connections on port 8000. Le connessioni sono protette da TLS con un certificato incluso:Connections are secured by TLS with a supplied certificate:

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

Facoltativamente, creare un'implementazione IConnectionAdapter per filtrare gli handshake TLS in base alla connessione in caso di crittografie specifiche: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.
        //
        // 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()
        {
        }
    }
}

Impostare il protocollo dalla configurazioneSet the protocol from configuration

CreateDefaultBuilder chiama serverOptions.Configure(context.Configuration.GetSection("Kestrel")) per impostazione predefinita per caricare la configurazione di Kestrel.CreateDefaultBuilder calls serverOptions.Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration.

Nell'esempio appsettings.json seguente viene stabilito un protocollo di connessione predefinito (HTTP/1.1 e HTTP/2) per tutti gli endpoint Kestrel: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"
    }
  }
}

Il file di configurazione di esempio seguente stabilisce un protocollo di connessione per un endpoint specifico:The following configuration file example establishes a connection protocol for a specific endpoint:

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

I protocolli specificati nei valori di override del codice sono impostati dalla configurazione.Protocols specified in code override values set by configuration.

Configurazione del trasportoTransport configuration

Con la versione ASP.NET Core 2.1, il trasporto predefinito di Kestrel non si basa più su Libuv, ma su socket gestiti.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. Si tratta di una modifica importante per le app ASP.NET 2.0 Core che vengono aggiornate alla versione 2.1, che chiamano UseLibuv e dipendono da uno dei pacchetti seguenti: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:

Per i progetti che richiedono l'uso di libuv:For projects that require the use of Libuv:

  • Aggiungere una dipendenza per il pacchetto Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al file di progetto dell'app: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}" />
    
  • Chiamare 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>();
    }
    

Prefissi URLURL prefixes

Se si usa UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls o la variabile di ambiente ASPNETCORE_URLS, i prefissi URL possono avere uno dei formati seguenti.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.

Sono validi solo i prefissi URL HTTP.Only HTTP URL prefixes are valid. Kestrel non supporta HTTPS quando la configurazione delle associazioni URL viene eseguita con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Indirizzo IPv4 con numero di portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 è un caso speciale che esegue l'associazione a tutti gli indirizzi IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Indirizzo IPv6 con numero di portaIPv6 address with port number

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

    [::] è l'equivalente IPv6 di 0.0.0.0 per IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome host con numero di portaHost name with port number

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

    I nomi host, * e + non sono casi particolari.Host names, *, and +, aren't special. Tutto ciò che non è riconosciuto come un indirizzo IP o un elemento localhost valido esegue l'associazione a tutti gli IP IPv4 e IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Per associare nomi host diversi ad app ASP.NET Core diverse sulla stessa porta, usare HTTP.sys o un server proxy inverso come IIS, Nginx o 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.

    Avviso

    Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome host localhost con numero di porta o IP di loopback con numero di portaHost localhost name with port number or loopback IP with port number

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

    Se è specificato localhost, Kestrel tenta l'associazione alle interfacce di loopback sia IPv4 che IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se la porta richiesta è in uso da parte di un altro servizio in una delle due interfacce di loopback, Kestrel non viene avviato.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se una delle due interfacce di loopback non è disponibile per qualsiasi altro motivo (in genere perché IPv6 non è supportato), Kestrel registra un avviso.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtro hostHost filtering

Mentre supporta la configurazione in base ai prefissi, ad esempio http://example.com:5000, Kestrel ignora quasi sempre il nome host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. L'host localhost è un caso speciale usato per l'associazione agli indirizzi di loopback.Host localhost is a special case used for binding to loopback addresses. Qualsiasi host che non sia un indirizzo IP esplicito esegue l'associazione a tutti gli indirizzi IP pubblici.Any host other than an explicit IP address binds to all public IP addresses. Le intestazioni Host non vengono convalidate.Host headers aren't validated.

Come soluzione alternativa, usare il middleware di filtro host.As a workaround, use Host Filtering Middleware. Il middleware di filtro host viene fornito dal pacchetto Microsoft. AspNetCore. HostFiltering , incluso nel metapacchetto Microsoft. AspNetCore. App (ASP.NET Core 2,1 o 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). Il middleware viene aggiunto da CreateDefaultBuilder, che chiama 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>();
}

Per impostazione predefinita, il middleware di filtro host è disabilitato per impostazione predefinita.Host Filtering Middleware is disabled by default. Per abilitare il middleware, definire una chiave AllowedHosts in appsettings.json/appsettings.<NomeAmbiente>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Il valore è un elenco con valori delimitati da punto e virgola di nomi host senza numeri di porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Il middleware delle intestazioni inoltrate include anche un'opzione AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Il middleware di intestazioni inoltrate e il middleware di filtro host hanno funzionalità simili per diversi scenari.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. L'impostazione di AllowedHosts con il middleware delle intestazioni inoltrate è appropriato se l'intestazione Host non viene mantenuta durante l'inoltro delle richieste con un server proxy inverso o il bilanciamento del carico.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. L'impostazione di AllowedHosts con il middleware del filtro host è appropriata se si usa Kestrel come server perimetrale rivolto al pubblico o se l'intestazione Host viene inoltrata direttamente.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.

Per altre informazioni sul middleware delle intestazioni inoltrate, vedere Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.For more information on Forwarded Headers Middleware, see Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.

Kestrel è un server Web per ASP.NET Core multipiattaforma.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel è il server Web incluso per impostazione predefinita nei modelli di progetto di ASP.NET Core.Kestrel is the web server that's included by default in ASP.NET Core project templates.

Kestrel supporta gli scenari seguenti:Kestrel supports the following scenarios:

  • HTTPSHTTPS
  • Aggiornamento opaco usato per abilitare WebSocketOpaque upgrade used to enable WebSockets
  • Socket Unix ad alte prestazioni dietro NginxUnix sockets for high performance behind Nginx

Kestrel è supportato in tutte le piattaforme e le versioni supportate da .NET Core.Kestrel is supported on all platforms and versions that .NET Core supports.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Quando usare Kestrel con un proxy inversoWhen to use Kestrel with a reverse proxy

È possibile usare Kestrel da solo o in combinazione con un server proxy inverso, ad esempio Internet Information Services (IIS), Nginx o Apache.Kestrel can be used by itself or with a reverse proxy server, such as Internet Information Services (IIS), Nginx, or Apache. Il server proxy inverso riceve le richieste HTTP dalla rete e le inoltra a Kestrel.A reverse proxy server receives HTTP requests from the network and forwards them to Kestrel.

Kestrel usato come server Web perimetrale (esposto a Internet):Kestrel used as an edge (Internet-facing) web server:

Kestrel comunica direttamente con Internet senza un server proxy inverso

Kestrel usato in una configurazione proxy inverso:Kestrel used in a reverse proxy configuration:

Kestrel comunica indirettamente con Internet attraverso un server proxy inverso, ad esempio IIS, Nginx o Apache

La configurazione, con o senza un server proxy inverso, è una configurazione di hosting supportata.Either configuration, with or without a reverse proxy server, is a supported hosting configuration.

Se viene utilizzato come server perimetrale in assenza di un server proxy inverso, Kestrel non supporta la condivisione tra più processi dell'IP e della porta.Kestrel used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes. Quando è configurato per restare in ascolto su una porta, Kestrel gestisce tutto il traffico per tale porta indipendentemente dalle intestazioni Host delle richieste.When Kestrel is configured to listen on a port, Kestrel handles all of the traffic for that port regardless of requests' Host headers. Un proxy inverso che può condividere le porte può eseguire l'inoltro delle richieste a Kestrel su un unico IP e un'unica porta.A reverse proxy that can share ports has the ability to forward requests to Kestrel on a unique IP and port.

Anche se la presenza di un server proxy inverso non è necessaria, può risultare utile per i motivi seguenti.Even if a reverse proxy server isn't required, using a reverse proxy server might be a good choice.

Un proxy inverso:A reverse proxy:

  • Può limitare l'area della superficie di attacco pubblica esposta delle app ospitate.Can limit the exposed public surface area of the apps that it hosts.
  • Offre un livello aggiuntivo di configurazione e protezione.Provide an additional layer of configuration and defense.
  • Potrebbe offrire un'integrazione migliore con l'infrastruttura esistente.Might integrate better with existing infrastructure.
  • Semplifica il bilanciamento del carico e la configurazione di comunicazioni protette (HTTPS).Simplify load balancing and secure communication (HTTPS) configuration. Solo il server proxy inverso richiede un certificato X. 509 e il server è in grado di comunicare con i server dell'app nella rete interna tramite HTTP normale.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.

Avviso

Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

Come usare Kestrel nelle app ASP.NET CoreHow to use Kestrel in ASP.NET Core apps

Il pacchetto Microsoft. AspNetCore. Server. gheppio è incluso nel metapacchetto Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Server.Kestrel package is included in the Microsoft.AspNetCore.App metapackage.

I modelli di progetto ASP.NET Core usano Kestrel per impostazione predefinita.ASP.NET Core project templates use Kestrel by default. In Program.cs il codice del modello chiama CreateDefaultBuilder, che chiama UseKestrel in background.In Program.cs, the template code calls CreateDefaultBuilder, which calls UseKestrel behind the scenes.

Per fornire una configurazione aggiuntiva dopo la chiamata di CreateDefaultBuilder, chiamare 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
        });

Opzioni KestrelKestrel options

Il server Web Kestrel dispone di opzioni di configurazione dei vincoli che risultano particolarmente utili nelle distribuzioni con connessione Internet.The Kestrel web server has constraint configuration options that are especially useful in Internet-facing deployments.

Impostare i vincoli per la proprietà Limits della classe KestrelServerOptions.Set constraints on the Limits property of the KestrelServerOptions class. La proprietà Limits contiene un'istanza della classe KestrelServerLimits.The Limits property holds an instance of the KestrelServerLimits class.

Negli esempi seguenti viene usato lo spazio dei nomi Microsoft.AspNetCore.Server.Kestrel.Core:The following examples use the Microsoft.AspNetCore.Server.Kestrel.Core namespace:

using Microsoft.AspNetCore.Server.Kestrel.Core;

Timeout keep-aliveKeep-alive timeout

KeepAliveTimeout

Ottiene o imposta il timeout keep-alive.Gets or sets the keep-alive timeout. Il valore predefinito è 2 minuti.Defaults to 2 minutes.

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

Numero massimo di connessioni clientMaximum client connections

MaxConcurrentConnections MaxConcurrentUpgradedConnections

È possibile impostare il numero massimo di connessioni TCP aperte simultaneamente per l'intera app con il codice seguente:The maximum number of concurrent open TCP connections can be set for the entire app with the following code:

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

È previsto un limite separato per le connessioni che sono state aggiornate da HTTP o HTTPS a un altro protocollo (ad esempio su una richiesta 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). Dopo l'aggiornamento di una connessione, questa non viene conteggiata per il limite MaxConcurrentConnections.After a connection is upgraded, it isn't counted against the MaxConcurrentConnections limit.

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

Per impostazione predefinita, il numero massimo di connessioni è illimitato (null).The maximum number of connections is unlimited (null) by default.

Dimensione massima del corpo della richiestaMaximum request body size

MaxRequestBodySize

La dimensione massima predefinita del corpo della richiesta è pari a 30.000.000 di byte, equivalenti a circa 28,6 MB.The default maximum request body size is 30,000,000 bytes, which is approximately 28.6 MB.

Il metodo consigliato per ignorare il limite in un'app ASP.NET Core MVC è l'uso dell'attributo RequestSizeLimitAttribute in un metodo di azione: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()

L'esempio seguente illustra come configurare il vincolo per l'app in ogni richiesta: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;
        });

Eseguire l'override dell'impostazione per una richiesta specifica nel middleware: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));
    }

Viene generata un'eccezione se l'app configura il limite per una richiesta dopo che l'app ha iniziato a leggere la richiesta.An exception is thrown if the app configures the limit on a request after the app has started to read the request. Una proprietà IsReadOnly indica se la proprietà MaxRequestBodySize è in stato di sola lettura e pertanto è troppo tardi per configurare il limite.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.

Quando un'app viene eseguita out-of-process dietro il modulo ASP.NET Core, il limite della dimensione del corpo della richiesta di Kestrel è disabilitato perché viene già impostato da 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.

Velocità minima dei dati del corpo della richiestaMinimum request body data rate

MinRequestBodyDataRate MinResponseDataRate

Kestrel controlla ogni secondo se i dati arrivano alla velocità in byte al secondo specificata.Kestrel checks every second if data is arriving at the specified rate in bytes/second. Se la velocità scende sotto il valore minimo, la connessione raggiunge il timeout. Il periodo di tolleranza è la quantità di tempo che Kestrel concede al client per aumentare la velocità di trasmissione fino al valore minimo. Durante tale periodo la velocità non viene rilevata.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. Il periodo di prova consente di evitare l'interruzione di connessioni che inizialmente inviano i dati a velocità ridotta a causa dell'avvio lento del protocollo TCP.The grace period helps avoid dropping connections that are initially sending data at a slow rate due to TCP slow-start.

La velocità minima predefinita è di 240 byte al secondo, con un periodo di tolleranza di 5 secondi.The default minimum rate is 240 bytes/second with a 5 second grace period.

Anche per la risposta è prevista una velocità minima.A minimum rate also applies to the response. Il codice per impostare il limite della richiesta e della risposta è identico e varia solo per RequestBody o Response nei nomi di proprietà e di interfaccia.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.

L'esempio seguente visualizza come configurare la velocità minima dei dati in 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));
        });

Timeout delle intestazioni delle richiesteRequest headers timeout

RequestHeadersTimeout

Ottiene o imposta la quantità massima di tempo che il server dedica alla ricezione delle intestazioni delle richieste.Gets or sets the maximum amount of time the server spends receiving request headers. Il valore predefinito è 30 secondi.Defaults to 30 seconds.

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

I/O sincronoSynchronous IO

AllowSynchronousIO controlla se l'I/O sincrono è consentito per la richiesta e la risposta.AllowSynchronousIO controls whether synchronous IO is allowed for the request and response. Il valore predefinito è true.The default value is true.

Avviso

Un numero elevato di operazioni di I/O sincrone bloccanti può portare alla scadenza del pool di thread, a causa della quale l'app smette di rispondere.A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Abilitare solo AllowSynchronousIO quando si usa una libreria che non supporta l'I/O asincrono.Only enable AllowSynchronousIO when using a library that doesn't support asynchronous IO.

L'esempio seguente disabilita l'I/O sincrono:The following example disables synchronous IO:

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

Per informazioni su altre opzioni e limiti di Kestrel, vedere:For information about other Kestrel options and limits, see:

Configurazione dell'endpointEndpoint configuration

Per impostazione predefinita, ASP.NET Core è associato a:By default, ASP.NET Core binds to:

  • http://localhost:5000
  • https://localhost:5001 (quando è presente un certificato di sviluppo locale)https://localhost:5001 (when a local development certificate is present)

Specificare gli URL usando gli elementi seguenti:Specify URLs using the:

  • La variabile di ambiente ASPNETCORE_URLS.ASPNETCORE_URLS environment variable.
  • L'argomento della riga di comando --urls.--urls command-line argument.
  • La chiave di configurazione dell'host urls.urls host configuration key.
  • Il metodo di estensione UseUrls.UseUrls extension method.

Il valore specificato usando i metodi seguenti può essere uno o più endpoint HTTP e HTTPS (HTTPS se è disponibile un certificato predefinito).The value provided using these approaches can be one or more HTTP and HTTPS endpoints (HTTPS if a default cert is available). Configurare il valore come un elenco delimitato da punto e virgola (ad esempio, "Urls": "http://localhost:8000; http://localhost:8001").Configure the value as a semicolon-separated list (for example, "Urls": "http://localhost:8000;http://localhost:8001").

Per altre informazioni su questi approcci, vedere URL del server e Override della configurazione.For more information on these approaches, see Server URLs and Override configuration.

Viene creato un certificato di sviluppo nei casi seguenti:A development certificate is created:

Alcuni browser richiedono la concessione di autorizzazioni esplicite per considerare attendibile il certificato di sviluppo locale.Some browsers require granting explicit permission to trust the local development certificate.

I modelli di progetto consentono di configurare le app per l'esecuzione su HTTPS per impostazione predefinita e includono il reindirizzamento HTTPS e il supporto HSTS.Project templates configure apps to run on HTTPS by default and include HTTPS redirection and HSTS support.

Chiamare i metodi Listen oppure ListenUnixSocket su KestrelServerOptions per configurare le porte e i prefissi URL per Kestrel.Call Listen or ListenUnixSocket methods on KestrelServerOptions to configure URL prefixes and ports for Kestrel.

Anche UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls e la variabile di ambiente ASPNETCORE_URLS funzionano, ma con le limitazioni indicate più avanti nella sezione (deve essere disponibile un certificato predefinito per la configurazione dell'endopoint 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).

KestrelServerOptionsconfigurazioneKestrelServerOptions configuration:

ConfigureEndpointDefaults (azione<ListenOptions >)ConfigureEndpointDefaults(Action<ListenOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint specificato.Specifies a configuration Action to run for each specified endpoint. Se si chiama ConfigureEndpointDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureEndpointDefaults multiple times replaces prior Actions with the last Action specified.

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

ConfigureHttpsDefaults (azione<HttpsConnectionAdapterOptions >)ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Specifica un elemento di configurazione Action da eseguire per ogni endpoint HTTPS.Specifies a configuration Action to run for each HTTPS endpoint. Se si chiama ConfigureHttpsDefaults più volte, gli elementi Action precedenti vengono sostituiti con l'ultimo elemento Action specificato.Calling ConfigureHttpsDefaults multiple times replaces prior Actions with the last Action specified.

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)

Crea un loader di configurazione per la configurazione di Kestrel che accetta un elemento IConfiguration come input.Creates a configuration loader for setting up Kestrel that takes an IConfiguration as input. L'ambito della configurazione deve essere la sezione di configurazione per Kestrel.The configuration must be scoped to the configuration section for Kestrel.

ListenOptions.UseHttpsListenOptions.UseHttps

Configura Kestrel per l'uso di HTTPS.Configure Kestrel to use HTTPS.

Estensioni ListenOptions.UseHttps:ListenOptions.UseHttps extensions:

  • UseHttps - Configura Kestrel per l'uso di HTTPS con il certificato predefinito.UseHttps – Configure Kestrel to use HTTPS with the default certificate. Genera un'eccezione se non è stato configurato alcun certificato predefinito.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)

Parametri ListenOptions.UseHttps:ListenOptions.UseHttps parameters:

  • filename è il percorso e il nome file di un file di certificato, relativo alla directory che contiene i file di contenuto dell'app.filename is the path and file name of a certificate file, relative to the directory that contains the app's content files.
  • password è la password richiesta per accedere ai dati del certificato X.509.password is the password required to access the X.509 certificate data.
  • configureOptions è un elemento Action per configurare HttpsConnectionAdapterOptions.configureOptions is an Action to configure the HttpsConnectionAdapterOptions. Restituisce ListenOptions.Returns the ListenOptions.
  • storeName è l'archivio certificati da cui caricare il certificato.storeName is the certificate store from which to load the certificate.
  • subject è il nome dell'oggetto del certificato.subject is the subject name for the certificate.
  • allowInvalid indica se devono essere considerati i certificati non validi, come ad esempio i certificati autofirmati.allowInvalid indicates if invalid certificates should be considered, such as self-signed certificates.
  • location è il percorso dell'archivio da cui caricare il certificato.location is the store location to load the certificate from.
  • serverCertificate è il certificato X.509.serverCertificate is the X.509 certificate.

Nell'ambiente di produzione, HTTPS deve essere configurato in modo esplicito.In production, HTTPS must be explicitly configured. Come minimo, è necessario specificare un certificato predefinito.At a minimum, a default certificate must be provided.

Configurazioni supportate descritte in seguito:Supported configurations described next:

  • Nessuna configurazioneNo configuration
  • Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration
  • Modificare le impostazioni predefinite nel codiceChange the defaults in code

Nessuna configurazioneNo configuration

Kestrel è in ascolto su http://localhost:5000 e https://localhost:5001 (se è disponibile un certificato predefinito).Kestrel listens on http://localhost:5000 and https://localhost:5001 (if a default cert is available).

Sostituire il certificato predefinito della configurazioneReplace the default certificate from configuration

CreateDefaultBuilder chiama Configure(context.Configuration.GetSection("Kestrel")) per impostazione predefinita per caricare la configurazione di Kestrel.CreateDefaultBuilder calls Configure(context.Configuration.GetSection("Kestrel")) by default to load Kestrel configuration. È disponibile per Kestrel uno schema di configurazione delle impostazioni delle app HTTPS predefinito.A default HTTPS app settings configuration schema is available for Kestrel. Configurare più endpoint, inclusi gli URL e i certificati da usare, da un file su disco o da un archivio certificati.Configure multiple endpoints, including the URLs and the certificates to use, either from a file on disk or from a certificate store.

Nel file appsettings.json di esempio seguente:In the following appsettings.json example:

  • Impostare AllowInvalid su true per consentire l'uso di certificati non validi, come ad esempio i certificati autofirmati.Set AllowInvalid to true to permit the use of invalid certificates (for example, self-signed certificates).
  • Tutti gli endpoint HTTPS che non specificano un certificato (HttpsDefaultCert nell'esempio che segue) usano il certificato definito in Certificates > Default o il certificato di sviluppo.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>"
      }
    }
  }
}

Un'alternativa all'uso di Path e Password per qualsiasi nodo del certificato consiste nello specificare il certificato usando i campi dell'archivio certificati.An alternative to using Path and Password for any certificate node is to specify the certificate using certificate store fields. Ad esempio, il certificato specificato mediante Certificates > Default può essere specificato come: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>"
}

Note di schema:Schema notes:

  • I nomi degli endpoint non applicano la distinzione tra maiuscole e minuscole.Endpoints names are case-insensitive. Ad esempio, sono validi sia HTTPS che Https.For example, HTTPS and Https are valid.
  • Il parametro Url è obbligatorio per ogni endpoint.The Url parameter is required for each endpoint. Il formato per questo parametro è uguale a quello del parametro di configurazione di primo livello Urls, con la differenza che si limita a un singolo valore.The format for this parameter is the same as the top-level Urls configuration parameter except that it's limited to a single value.
  • Questi endpoint sostituiscono quelli definiti nella configurazione di primo livello Urls, non vi si aggiungono.These endpoints replace those defined in the top-level Urls configuration rather than adding to them. Gli endpoint definiti nel codice tramite Listen si aggiungono agli endpoint definiti nella sezione di configurazione.Endpoints defined in code via Listen are cumulative with the endpoints defined in the configuration section.
  • La sezione Certificate è facoltativa.The Certificate section is optional. Se la sezione Certificate non è specificata, vengono usati i valori predefiniti definiti negli scenari precedenti.If the Certificate section isn't specified, the defaults defined in earlier scenarios are used. Se non è disponibile alcun valore predefinito, il server genera un'eccezione e non viene avviato.If no defaults are available, the server throws an exception and fails to start.
  • La sezione Certificate supporta sia i certificati PathPassword che i certificati SubjectStore.The Certificate section supports both PathPassword and SubjectStore certificates.
  • In questo modo è possibile definire un numero qualsiasi di endpoint, purché non provochino conflitti di porte.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}")) restituisce un oggetto KestrelConfigurationLoader con un metodo .Endpoint(string name, listenOptions => { }) che può essere usato per integrare le impostazioni dell'endpoint configurato: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;
                });
        });

KestrelServerOptions.ConfigurationLoaderè possibile accedere direttamente a per continuare a scorrere sul caricatore esistente, ad esempio quello fornito da CreateDefaultBuilder.KestrelServerOptions.ConfigurationLoader can be directly accessed to continue iterating on the existing loader, such as the one provided by CreateDefaultBuilder.

  • La sezione di configurazione per ogni endpoint è disponibile sulle opzioni nel metodo Endpoint in modo che le impostazioni personalizzate possano essere lette.The configuration section for each endpoint is a available on the options in the Endpoint method so that custom settings may be read.
  • È possibile caricare più configurazioni chiamando ancora options.Configure(context.Configuration.GetSection("{SECTION}")) con un'altra sezione.Multiple configurations may be loaded by calling options.Configure(context.Configuration.GetSection("{SECTION}")) again with another section. Viene usata solo l'ultima configurazione, a meno che Load sia stato chiamato esplicitamente in istanze precedenti.Only the last configuration is used, unless Load is explicitly called on prior instances. Il metapacchetto non chiama Load in modo che la sezione di configurazione predefinita venga sostituita.The metapackage doesn't call Load so that its default configuration section may be replaced.
  • KestrelConfigurationLoader riflette la famiglia di API Listen da KestrelServerOptions all'overload di Endpoint, in modo che gli endpoint di codice e di configurazione possano essere configurati nella stessa posizione.KestrelConfigurationLoader mirrors the Listen family of APIs from KestrelServerOptions as Endpoint overloads, so code and config endpoints may be configured in the same place. Questi overload non usano nomi e usano solo le impostazioni predefinite della configurazione.These overloads don't use names and only consume default settings from configuration.

Modificare le impostazioni predefinite nel codiceChange the defaults in code

ConfigureEndpointDefaults e ConfigureHttpsDefaults possono essere usati per modificare le impostazioni predefinite per ListenOptions e HttpsConnectionAdapterOptions, inclusa l'esecuzione dell'override del certificato predefinito specificato nello scenario precedente.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 e ConfigureHttpsDefaults devono essere chiamati prima che venga configurato qualsiasi endpoint.ConfigureEndpointDefaults and ConfigureHttpsDefaults should be called before any endpoints are configured.

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

Supporto kestrel per SNIKestrel support for SNI

L'Indicazione nome server (SNI) può essere usata per ospitare più domini sulla stessa porta e indirizzo IP.Server Name Indication (SNI) can be used to host multiple domains on the same IP address and port. Perché SNI funzioni è necessario che il client invii al server il nome host per la sessione protetta durante l'handshake TLS in modo che il server possa specificare il certificato corretto.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. Il client usa il certificato specificato per la comunicazione crittografata con il server durante la sessione protetta che segue l'handshake TLS.The client uses the furnished certificate for encrypted communication with the server during the secure session that follows the TLS handshake.

Kestrel supporta SNI tramite il callback ServerCertificateSelector.Kestrel supports SNI via the ServerCertificateSelector callback. Il callback viene richiamato una volta per ogni connessione per consentire all'app di controllare il nome host e selezionare il certificato appropriato.The callback is invoked once per connection to allow the app to inspect the host name and select the appropriate certificate.

Il supporto SNI richiede:SNI support requires:

  • In esecuzione su Framework netcoreapp2.1 di destinazione o versione successiva.Running on target framework netcoreapp2.1 or later. In net461 o versioni successive, il callback viene richiamato name , ma nullè sempre.On net461 or later, the callback is invoked but the name is always null. L'elemento name è null anche se il client non specifica il parametro del nome host nell'handshake TLS.The name is also null if the client doesn't provide the host name parameter in the TLS handshake.
  • Esecuzione di tutti i siti Web nella stessa istanza di Kestrel.All websites run on the same Kestrel instance. Kestrel supporta la condivisione di un indirizzo IP e di una porta tra più istanze solo con un proxy inverso.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();

Associazione a un socket TCPBind to a TCP socket

Il metodo Listen esegue l'associazione a un socket TCP e un'espressione lambda per le opzioni consente di configurare un certificato 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");
            });
        });

L'esempio configura HTTPS per un endpoint con ListenOptions.The example configures HTTPS for an endpoint with ListenOptions. Usare la stessa API per configurare altre impostazioni di Kestrel per endpoint specifici.Use the same API to configure other Kestrel settings for specific endpoints.

In Windows è possibile creare certificati autofirmati con il cmdlet di PowerShell New-SelfSignedCertificate.On Windows, self-signed certificates can be created using the New-SelfSignedCertificate PowerShell cmdlet. Per un esempio non supportato, vedere UpdateIISExpressSSLForChrome.ps1.For an unsupported example, see UpdateIISExpressSSLForChrome.ps1.

In macOS, Linux e Windows, i certificati possono essere creati con OpenSSL.On macOS, Linux, and Windows, certificates can be created using OpenSSL.

Associazione a un socket UnixBind to a Unix socket

Impostare l'ascolto su un socket Unix con ListenUnixSocket per migliorare le prestazioni con Nginx, come visualizzato nell'esempio seguente:Listen on a Unix socket with ListenUnixSocket for improved performance with Nginx, as shown in this example:

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

Porta 0Port 0

Quando si specifica il numero di porta 0, Kestrel esegue l'associazione dinamica a una porta disponibile.When the port number 0 is specified, Kestrel dynamically binds to an available port. L'esempio seguente indica come determinare la porta alla quale Kestrel ha eseguito l'associazione in fase di esecuzione: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>");
    });
}

Quando si esegue l'app, l'output della finestra della console indica la porta dinamica in cui l'app può essere raggiunta: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

LimitazioniLimitations

Configurare gli endpoint con i metodi seguenti:Configure endpoints with the following approaches:

  • UseUrls
  • L'argomento della riga di comando --urls--urls command-line argument
  • La chiave di configurazione dell'host urlsurls host configuration key
  • La variabile di ambiente ASPNETCORE_URLSASPNETCORE_URLS environment variable

Questi metodi sono utili se si vuole che il codice funzioni con server diversi da Kestrel.These methods are useful for making code work with servers other than Kestrel. Tenere presenti, tuttavia, le limitazioni seguenti:However, be aware of the following limitations:

  • HTTPS non può essere usato con questi approcci, a meno che non venga specificato un certificato predefinito nella configurazione dell'endpoint HTTPS (ad esempio, usando la configurazione KestrelServerOptions o un file di configurazione come illustrato in precedenza in questo argomento).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).
  • Quando sia l'approccio Listen che l'approccio UseUrls vengono usati contemporaneamente, gli endpoint Listen eseguono l'override degli endpoint UseUrls.When both the Listen and UseUrls approaches are used simultaneously, the Listen endpoints override the UseUrls endpoints.

Configurazione dell'endpoint IISIIS endpoint configuration

Quando si usa IIS, le associazioni di URL per le associazioni di override di IIS vengono impostate mediante Listen o UseUrls.When using IIS, the URL bindings for IIS override bindings are set by either Listen or UseUrls. Per altre informazioni, vedere l'articolo Introduzione al modulo ASP.NET Core.For more information, see the ASP.NET Core Module topic.

Configurazione del trasportoTransport configuration

Con la versione ASP.NET Core 2.1, il trasporto predefinito di Kestrel non si basa più su Libuv, ma su socket gestiti.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. Si tratta di una modifica importante per le app ASP.NET 2.0 Core che vengono aggiornate alla versione 2.1, che chiamano UseLibuv e dipendono da uno dei pacchetti seguenti: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:

Per i progetti che richiedono l'uso di libuv:For projects that require the use of Libuv:

  • Aggiungere una dipendenza per il pacchetto Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv al file di progetto dell'app: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}" />
    
  • Chiamare 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>();
    }
    

Prefissi URLURL prefixes

Se si usa UseUrls, l'argomento della riga di comando --urls, la chiave di configurazione dell'host urls o la variabile di ambiente ASPNETCORE_URLS, i prefissi URL possono avere uno dei formati seguenti.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.

Sono validi solo i prefissi URL HTTP.Only HTTP URL prefixes are valid. Kestrel non supporta HTTPS quando la configurazione delle associazioni URL viene eseguita con UseUrls.Kestrel doesn't support HTTPS when configuring URL bindings using UseUrls.

  • Indirizzo IPv4 con numero di portaIPv4 address with port number

    http://65.55.39.10:80/
    

    0.0.0.0 è un caso speciale che esegue l'associazione a tutti gli indirizzi IPv4.0.0.0.0 is a special case that binds to all IPv4 addresses.

  • Indirizzo IPv6 con numero di portaIPv6 address with port number

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

    [::] è l'equivalente IPv6 di 0.0.0.0 per IPv4.[::] is the IPv6 equivalent of IPv4 0.0.0.0.

  • Nome host con numero di portaHost name with port number

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

    I nomi host, * e + non sono casi particolari.Host names, *, and +, aren't special. Tutto ciò che non è riconosciuto come un indirizzo IP o un elemento localhost valido esegue l'associazione a tutti gli IP IPv4 e IPv6.Anything not recognized as a valid IP address or localhost binds to all IPv4 and IPv6 IPs. Per associare nomi host diversi ad app ASP.NET Core diverse sulla stessa porta, usare HTTP.sys o un server proxy inverso come IIS, Nginx o 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.

    Avviso

    Una configurazione che prevede un proxy inverso richiede il filtro host.Hosting in a reverse proxy configuration requires host filtering.

  • Nome host localhost con numero di porta o IP di loopback con numero di portaHost localhost name with port number or loopback IP with port number

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

    Se è specificato localhost, Kestrel tenta l'associazione alle interfacce di loopback sia IPv4 che IPv6.When localhost is specified, Kestrel attempts to bind to both IPv4 and IPv6 loopback interfaces. Se la porta richiesta è in uso da parte di un altro servizio in una delle due interfacce di loopback, Kestrel non viene avviato.If the requested port is in use by another service on either loopback interface, Kestrel fails to start. Se una delle due interfacce di loopback non è disponibile per qualsiasi altro motivo (in genere perché IPv6 non è supportato), Kestrel registra un avviso.If either loopback interface is unavailable for any other reason (most commonly because IPv6 isn't supported), Kestrel logs a warning.

Filtro hostHost filtering

Mentre supporta la configurazione in base ai prefissi, ad esempio http://example.com:5000, Kestrel ignora quasi sempre il nome host.While Kestrel supports configuration based on prefixes such as http://example.com:5000, Kestrel largely ignores the host name. L'host localhost è un caso speciale usato per l'associazione agli indirizzi di loopback.Host localhost is a special case used for binding to loopback addresses. Qualsiasi host che non sia un indirizzo IP esplicito esegue l'associazione a tutti gli indirizzi IP pubblici.Any host other than an explicit IP address binds to all public IP addresses. Le intestazioni Host non vengono convalidate.Host headers aren't validated.

Come soluzione alternativa, usare il middleware di filtro host.As a workaround, use Host Filtering Middleware. Il middleware di filtro host viene fornito dal pacchetto Microsoft. AspNetCore. HostFiltering , incluso nel metapacchetto Microsoft. AspNetCore. App (ASP.NET Core 2,1 o 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). Il middleware viene aggiunto da CreateDefaultBuilder, che chiama 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>();
}

Per impostazione predefinita, il middleware di filtro host è disabilitato per impostazione predefinita.Host Filtering Middleware is disabled by default. Per abilitare il middleware, definire una chiave AllowedHosts in appsettings.json/appsettings.<NomeAmbiente>.json.To enable the middleware, define an AllowedHosts key in appsettings.json/appsettings.<EnvironmentName>.json. Il valore è un elenco con valori delimitati da punto e virgola di nomi host senza numeri di porta:The value is a semicolon-delimited list of host names without port numbers:

appsettings.json:appsettings.json:

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

Nota

Il middleware delle intestazioni inoltrate include anche un'opzione AllowedHosts.Forwarded Headers Middleware also has an AllowedHosts option. Il middleware di intestazioni inoltrate e il middleware di filtro host hanno funzionalità simili per diversi scenari.Forwarded Headers Middleware and Host Filtering Middleware have similar functionality for different scenarios. L'impostazione di AllowedHosts con il middleware delle intestazioni inoltrate è appropriato se l'intestazione Host non viene mantenuta durante l'inoltro delle richieste con un server proxy inverso o il bilanciamento del carico.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. L'impostazione di AllowedHosts con il middleware del filtro host è appropriata se si usa Kestrel come server perimetrale rivolto al pubblico o se l'intestazione Host viene inoltrata direttamente.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.

Per altre informazioni sul middleware delle intestazioni inoltrate, vedere Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.For more information on Forwarded Headers Middleware, see Configurare ASP.NET Core per l'uso di server proxy e servizi di bilanciamento del carico.

Risorse aggiuntiveAdditional resources