Host Web ASP.NET CoreASP.NET Core Web Host

Di Luke LathamBy Luke Latham

Le app ASP.NET Core configurano e avviano un host.ASP.NET Core apps configure and launch a host. L'host è responsabile della gestione dell'avvio e della durata delle app.The host is responsible for app startup and lifetime management. L'host configura almeno un server e una pipeline di elaborazione delle richieste.At a minimum, the host configures a server and a request processing pipeline. L'host può anche configurare la registrazione, l'inserimento delle dipendenze e la configurazione.The host can also set up logging, dependency injection, and configuration.

Questo articolo descrive l'host Web, che rimane disponibile solo per compatibilità con le versioni precedenti.This article covers the Web Host, which remains available only for backward compatibility. L'host generico è consigliato per tutti i tipi di app.The Generic Host is recommended for all app types.

Questo articolo descrive l'host Web destinato all'hosting di app Web.This article covers the Web Host, which is for hosting web apps. Per altri tipi di app, usare l'host generico.For other kinds of apps, use the Generic Host.

Configurare un hostSet up a host

Creare un host usando un'istanza di IWebHostBuilder.Create a host using an instance of IWebHostBuilder. Questa operazione viene in genere eseguita nel punto di ingresso dell'app, il metodo Main.This is typically performed in the app's entry point, the Main method.

Nei modelli di progetto Main si trova in Program.cs.In the project templates, Main is located in Program.cs. Un'app tipica chiama CreateDefaultBuilder per avviare la configurazione di un host:A typical app calls CreateDefaultBuilder to start setting up a host:

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

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

Il codice che chiama CreateDefaultBuilder è incluso in un metodo denominato CreateWebHostBuilder, che lo separa dal codice in Main che chiama Run per l'oggetto generatore.The code that calls CreateDefaultBuilder is in a method named CreateWebHostBuilder, which separates it from the code in Main that calls Run on the builder object. Questa separazione è necessaria se si usano gli strumenti di Entity Framework Core.This separation is required if you use Entity Framework Core tools. Gli strumenti si aspettano di trovare un metodo CreateWebHostBuilder che possono chiamare in fase di progettazione per configurare l'host senza eseguire l'app.The tools expect to find a CreateWebHostBuilder method that they can call at design time to configure the host without running the app. Un'alternativa consiste nell'implementare IDesignTimeDbContextFactory.An alternative is to implement IDesignTimeDbContextFactory. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.For more information, see Design-time DbContext Creation.

CreateDefaultBuilder esegue le attività seguenti:CreateDefaultBuilder performs the following tasks:

La configurazione definita da CreateDefaultBuilder può essere sottoposta a override e aumentata tramite ConfigureAppConfiguration, ConfigureLogging e altri metodi e metodi di estensione di IWebHostBuilder.The configuration defined by CreateDefaultBuilder can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. Di seguito sono riportati alcuni esempi:A few examples follow:

  • ConfigureAppConfiguration viene usato per specificare altri elementi IConfiguration per l'app.ConfigureAppConfiguration is used to specify additional IConfiguration for the app. La chiamata a ConfigureAppConfiguration seguente consente di aggiungere un delegato per includere la configurazione dell'app nel file appsettings.xml.The following ConfigureAppConfiguration call adds a delegate to include app configuration in the appsettings.xml file. ConfigureAppConfiguration può essere chiamato più volte.ConfigureAppConfiguration may be called multiple times. Si noti che questa configurazione non è valida per l'host (ad esempio, gli URL del server o l'ambiente).Note that this configuration doesn't apply to the host (for example, server URLs or environment). Vedere la sezione Valori di configurazione dell'host.See the Host configuration values section.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • La chiamata a ConfigureLogging seguente consente di aggiungere un delegato per configurare il livello di registrazione minimo (SetMinimumLevel) LogLevel.Warning.The following ConfigureLogging call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. Questa impostazione sostituisce le impostazioni in appsettings.Development.json (LogLevel.Debug) e appsettings.Production.json (LogLevel.Error) configurate da CreateDefaultBuilder.This setting overrides the settings in appsettings.Development.json (LogLevel.Debug) and appsettings.Production.json (LogLevel.Error) configured by CreateDefaultBuilder. ConfigureLogging può essere chiamato più volte.ConfigureLogging may be called multiple times.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • La chiamata a ConfigureKestrel seguente sostituisce il valore predefinito Limits.MaxRequestBodySize di 30.000.000 di byte stabilito durante la configurazione del Kestrel da CreateDefaultBuilder:The following call to ConfigureKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    
  • La chiamata a UseKestrel seguente sostituisce il valore predefinito Limits.MaxRequestBodySize di 30.000.000 di byte stabilito durante la configurazione del Kestrel da CreateDefaultBuilder:The following call to UseKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(options =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

La radice del contenuto determina la posizione in cui l'host cerca i file dei contenuti, ad esempio i file di visualizzazione MVC.The content root determines where the host searches for content files, such as MVC view files. Quando l'app viene avviata dalla cartella radice del progetto, la cartella radice del progetto viene usata come radice del contenuto.When the app is started from the project's root folder, the project's root folder is used as the content root. Si tratta dell'impostazione predefinita usata in Visual Studio e nei nuovi modelli dotnet.This is the default used in Visual Studio and the dotnet new templates.

Per altre informazioni sulla configurazione dell'app, vedere Configurazione in ASP.NET Core.For more information on app configuration, see Configurazione in ASP.NET Core.

Nota

In alternativa all'uso del metodo CreateDefaultBuilder statico, un approccio supportato in ASP.NET Core 2.x consiste nel creare un host da WebHostBuilder.As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.

Quando si configura un host, è possibile specificare i metodi Configure e ConfigureServices.When setting up a host, Configure and ConfigureServices methods can be provided. Se viene specificata una classe Startup, la classe deve definire un metodo Configure.If a Startup class is specified, it must define a Configure method. Per altre informazioni, vedere Avvio dell'app in ASP.NET Core.For more information, see Avvio dell'app in ASP.NET Core. Se vengono effettuate più chiamate a ConfigureServices, le chiamate vengono aggiunte l'una all'altra.Multiple calls to ConfigureServices append to one another. Più chiamate a Configure o UseStartup in WebHostBuilder sostituiscono le impostazioni precedenti.Multiple calls to Configure or UseStartup on the WebHostBuilder replace previous settings.

Valori di configurazione dell'hostHost configuration values

WebHostBuilder si basa sugli approcci seguenti per impostare i valori di configurazione dell'host:WebHostBuilder relies on the following approaches to set the host configuration values:

  • Configurazione del generatore di host, che include le variabili di ambiente nel formato ASPNETCORE_{configurationKey}.Host builder configuration, which includes environment variables with the format ASPNETCORE_{configurationKey}. Ad esempio ASPNETCORE_ENVIRONMENT.For example, ASPNETCORE_ENVIRONMENT.
  • Le estensioni come UseContentRoot e UseConfiguration (vedere la sezione Override della configurazione).Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
  • UseSetting e chiave associata.UseSetting and the associated key. Quando si imposta un valore con UseSetting, il valore viene impostato come stringa indipendentemente dal tipo.When setting a value with UseSetting, the value is set as a string regardless of the type.

L'host usa l'ultima opzione che imposta un valore.The host uses whichever option sets a value last. Per altre informazioni, vedere Override della configurazione nella prossima sezione.For more information, see Override configuration in the next section.

Chiave applicazione (nome)Application Key (Name)

La proprietà IHostingEnvironment.ApplicationName viene impostata automaticamente quando si chiama UseStartup o Configure durante la costruzione dell'host.The IHostingEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called during host construction. Il valore viene impostato sul nome dell'assembly contenente il punto di ingresso dell'app.The value is set to the name of the assembly containing the app's entry point. Per impostare il valore in modo esplicito, usare WebHostDefaults.ApplicationKey:To set the value explicitly, use the WebHostDefaults.ApplicationKey:

Chiave: applicationNameKey: applicationName
Tipo: stringType: string
Impostazione predefinita: nome dell'assembly contenente il punto di ingresso dell'app.Default: The name of the assembly containing the app's entry point.
Impostare usando: UseSettingSet using: UseSetting
Variabile di ambiente: ASPNETCORE_APPLICATIONNAMEEnvironment variable: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Acquisizione degli errori di avvioCapture Startup Errors

Questa impostazione controlla l'acquisizione degli errori di avvio.This setting controls the capture of startup errors.

Chiave: captureStartupErrorsKey: captureStartupErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Impostazione predefinita: il valore predefinito è false, a meno che l'app non venga eseguita con Kestrel in IIS; in tal caso il valore predefinito è true.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Impostare usando: CaptureStartupErrorsSet using: CaptureStartupErrors
Variabile di ambiente: ASPNETCORE_CAPTURESTARTUPERRORSEnvironment variable: ASPNETCORE_CAPTURESTARTUPERRORS

Quando è false, gli errori durante l'avvio causano la chiusura dell'host.When false, errors during startup result in the host exiting. Quando è true, l'host acquisisce le eccezioni durante l'avvio e tenta di avviare il server.When true, the host captures exceptions during startup and attempts to start the server.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Radice del contenutoContent Root

Questa impostazione determina la posizione da cui ASP.NET Core inizia la ricerca dei file di contenuto, ad esempio delle visualizzazioni MVC.This setting determines where ASP.NET Core begins searching for content files, such as MVC views.

Chiave: contentRootKey: contentRoot
Tipo: stringType: string
Impostazione predefinita: il valore predefinito corrisponde alla cartella contenente l'assembly dell'app.Default: Defaults to the folder where the app assembly resides.
Impostare usando: UseContentRootSet using: UseContentRoot
Variabile di ambiente: ASPNETCORE_CONTENTROOTEnvironment variable: ASPNETCORE_CONTENTROOT

La radice del contenuto viene usata anche come percorso di base per l'impostazione della radice Web.The content root is also used as the base path for the Web Root setting. Se il percorso non esiste, l'host non verrà avviato.If the path doesn't exist, the host fails to start.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Errori dettagliatiDetailed Errors

Determina l'acquisizione degli errori dettagliati.Determines if detailed errors should be captured.

Chiave: detailedErrorsKey: detailedErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Impostazione predefinita: falseDefault: false
Impostare usando: UseSettingSet using: UseSetting
Variabile di ambiente: ASPNETCORE_DETAILEDERRORSEnvironment variable: ASPNETCORE_DETAILEDERRORS

Quando è abilitata (o quando l'ambiente è impostato su Development), l'app acquisisce le eccezioni dettagliate.When enabled (or when the Environment is set to Development), the app captures detailed exceptions.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

AmbienteEnvironment

Imposta l'ambiente dell'app.Sets the app's environment.

Chiave: environmentKey: environment
Tipo: stringType: string
Impostazione predefinita: ProduzioneDefault: Production
Impostare usando: UseEnvironmentSet using: UseEnvironment
Variabile di ambiente: ASPNETCORE_ENVIRONMENTEnvironment variable: ASPNETCORE_ENVIRONMENT

L'ambiente può essere impostato su qualsiasi valore.The environment can be set to any value. I valori definiti dal framework includono Development, Staging e Production.Framework-defined values include Development, Staging, and Production. Nei valori non viene fatta distinzione tra maiuscole e minuscole.Values aren't case sensitive. Per impostazione predefinita, l'ambiente viene letto dalla variabile di ambiente ASPNETCORE_ENVIRONMENT.By default, the Environment is read from the ASPNETCORE_ENVIRONMENT environment variable. Quando si usa Visual Studio, le variabili di ambiente possono essere impostate nel file launchSettings.json.When using Visual Studio, environment variables may be set in the launchSettings.json file. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.For more information, see Usare più ambienti in ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Assembly di avvio dell'hostingHosting Startup Assemblies

Imposta gli assembly di avvio dell'hosting dell'app.Sets the app's hosting startup assemblies.

Chiave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: stringType: string
Impostazione predefinita: Stringa vuotaDefault: Empty string
Impostare usando: UseSettingSet using: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da caricare all'avvio.A semicolon-delimited string of hosting startup assemblies to load on startup.

Sebbene il valore di configurazione predefinito sia una stringa vuota, gli assembly di avvio dell'hosting includono sempre l'assembly dell'app.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. Quando vengono specificati, gli assembly di avvio dell'hosting vengono aggiunti all'assembly dell'app per essere caricati quando l'app compila i servizi comuni durante l'avvio.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Porta HTTPSHTTPS Port

Impostare la porta di reindirizzamento HTTPS.Set the HTTPS redirect port. Usata per imporre HTTPS.Used in enforcing HTTPS.

Chiave: https_port Tipo: string Impostazione predefinita: non è impostato nessun valore predefinito.Key: https_port Type: string Default: A default value isn't set. Impostare usando: UseSetting Variabile di ambiente: ASPNETCORE_HTTPS_PORTSet using: UseSetting Environment variable: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Assembly di avvio dell'hosting da escludereHosting Startup Exclude Assemblies

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio.A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Chiave: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Tipo: stringType: string
Impostazione predefinita: Stringa vuotaDefault: Empty string
Impostare usando: UseSettingSet using: UseSetting
Variabile di ambiente: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferire gli URL di hostingPrefer Hosting URLs

Indica se l'host deve eseguire l'ascolto sugli URL configurati con WebHostBuilder anziché su quelli configurati con l'implementazione IServer.Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those configured with the IServer implementation.

Chiave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true o 1)Type: bool (true or 1)
Impostazione predefinita: trueDefault: true
Impostare usando: PreferHostingUrlsSet using: PreferHostingUrls
Variabile di ambiente: ASPNETCORE_PREFERHOSTINGURLSEnvironment variable: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Impedire l'avvio dell'hostingPrevent Hosting Startup

Impedisce il caricamento automatico degli assembly di avvio dell'hosting, inclusi gli assembly di avvio dell'hosting configurati dall'assembly dell'app.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Per altre informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.For more information, see Usare assembly di avvio dell'hosting in ASP.NET Core.

Chiave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true o 1)Type: bool (true or 1)
Impostazione predefinita: falseDefault: false
Impostare usando: UseSettingSet using: UseSetting
Variabile di ambiente: ASPNETCORE_PREVENTHOSTINGSTARTUPEnvironment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

URL del serverServer URLs

Indica gli indirizzi IP o gli indirizzi host con le porte e protocolli su cui il server deve eseguire l'ascolto per le richieste.Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.

Chiave: urlsKey: urls
Tipo: stringType: string
Default: http://localhost:5000Default: http://localhost:5000
Impostare usando: UseUrlsSet using: UseUrls
Variabile di ambiente: ASPNETCORE_URLSEnvironment variable: ASPNETCORE_URLS

Impostare su un elenco di prefissi URL separati da punto e virgola (;) ai quali il server deve rispondere.Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. Ad esempio http://localhost:123.For example, http://localhost:123. Usare "*" per indicare che il server deve eseguire l'ascolto per le richieste su tutti gli indirizzi IP o nomi host usando la porta e il protocollo specificati (ad esempio, http://*:5000).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). Il protocollo (http:// o https://) deve essere incluso con ogni URL.The protocol (http:// or https://) must be included with each URL. I formati supportati variano a seconda del server.Supported formats vary among servers.

WebHost.CreateDefaultBuilder(args)
    .UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")

Kestrel ha una propria API di configurazione degli endpoint.Kestrel has its own endpoint configuration API. Per altre informazioni, vedere Implementazione del server Web Kestrel in ASP.NET Core.For more information, see Implementazione del server Web Kestrel in ASP.NET Core.

Timeout di arrestoShutdown Timeout

Specifica il tempo di attesa per l'arresto dell'host Web.Specifies the amount of time to wait for Web Host to shut down.

Chiave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Impostazione predefinita: 5Default: 5
Impostare usando: UseShutdownTimeoutSet using: UseShutdownTimeout
Variabile di ambiente: ASPNETCORE_SHUTDOWNTIMEOUTSECONDSEnvironment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Sebbene la chiave accetti int con UseSetting (ad esempio, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), il metodo di estensione UseShutdownTimeout accetta TimeSpan.Although the key accepts an int with UseSetting (for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), the UseShutdownTimeout extension method takes a TimeSpan.

Durante il periodo di timeout, l'hosting:During the timeout period, hosting:

Se il periodo di timeout scade prima che siano stati arrestati tutti i servizi ospitati, gli eventuali servizi attivi rimanenti vengono interrotti quando l'app viene arrestata.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. I servizi si arrestano anche se non hanno completato l'elaborazione.The services stop even if they haven't finished processing. Se l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.If services require additional time to stop, increase the timeout.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Assembly di avvioStartup Assembly

Determina l'assembly per la ricerca della classe Startup.Determines the assembly to search for the Startup class.

Chiave: startupAssemblyKey: startupAssembly
Tipo: stringType: string
Impostazione predefinita: assembly dell'appDefault: The app's assembly
Impostare usando: UseStartupSet using: UseStartup
Variabile di ambiente: ASPNETCORE_STARTUPASSEMBLYEnvironment variable: ASPNETCORE_STARTUPASSEMBLY

È possibile fare riferimento all'assembly per nome (string) o per tipo (TStartup).The assembly by name (string) or type (TStartup) can be referenced. Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.If multiple UseStartup methods are called, the last one takes precedence.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Radice WebWeb Root

Imposta il percorso relativo degli asset statici dell'app.Sets the relative path to the app's static assets.

Chiave: webrootKey: webroot
Tipo: stringType: string
Impostazione predefinita: se non è specificato, il valore predefinito è "(Content Root)/wwwroot", se il percorso esiste.Default: If not specified, the default is "(Content Root)/wwwroot", if the path exists. Se il percorso non esiste, viene usato un provider di file no-op.If the path doesn't exist, then a no-op file provider is used.
Impostare usando: UseWebRootSet using: UseWebRoot
Variabile di ambiente: ASPNETCORE_WEBROOTEnvironment variable: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Override della configurazioneOverride configuration

Usare la Configurazione per configurare l'host Web.Use Configuration to configure Web Host. Nell'esempio seguente la configurazione dell'host è specificata facoltativamente nel file hostsettings.json.In the following example, host configuration is optionally specified in a hostsettings.json file. Qualsiasi configurazione caricata dal file hostsettings.json può essere sostituita dagli argomenti della riga di comando.Any configuration loaded from the hostsettings.json file may be overridden by command-line arguments. La configurazione compilata (in config) viene usata per configurare l'host con UseConfiguration.The built configuration (in config) is used to configure the host with UseConfiguration. La configurazione di IWebHostBuilder viene aggiunta alla configurazione dell'app, ma non il contrario: —ConfigureAppConfiguration non influenza la configurazione di IWebHostBuilder.IWebHostBuilder configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration doesn't affect the IWebHostBuilder configuration.

Esecuzione dell'override della configurazione specificata da UseUrls con prima la configurazione hostsettings.json e quindi con la configurazione dell'argomento della riga di comando:Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument config second:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:hostsettings.json:

{
    urls: "http://*:5005"
}

Nota

Il metodo di estensione UseConfiguration non è attualmente in grado di analizzare una sezione di configurazione restituita da GetSection (ad esempio, .UseConfiguration(Configuration.GetSection("section")).The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection (for example, .UseConfiguration(Configuration.GetSection("section")). Il metodo GetSection filtra le chiavi di configurazione per la sezione richiesta, ma lascia il nome di sezione sulle chiavi (ad esempio, section:urls, section:environment).The GetSection method filters the configuration keys to the section requested but leaves the section name on the keys (for example, section:urls, section:environment). Il metodo UseConfiguration prevede che le chiavi corrispondano alle chiavi WebHostBuilder (ad esempio, urls, environment).The UseConfiguration method expects the keys to match the WebHostBuilder keys (for example, urls, environment). La presenza del nome di sezione sulle chiavi impedisce ai valori della sezione di configurare l'host.The presence of the section name on the keys prevents the section's values from configuring the host. Questo problema verrà risolto in una delle prossime versioni.This issue will be addressed in an upcoming release. Per altre informazioni e soluzioni alternative, vedere Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.For more information and workarounds, see Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.

UseConfiguration copia solo le chiavi dall'elemento IConfiguration specificato nella configurazione del generatore di host.UseConfiguration only copies keys from the provided IConfiguration to the host builder configuration. Pertanto, l'impostazione di reloadOnChange: true per i file JSON, INI e XML non ha alcun effetto.Therefore, setting reloadOnChange: true for JSON, INI, and XML settings files has no effect.

Per specificare l'host eseguito in un URL specifico, il valore desiderato può essere passato da un prompt dei comandi durante l'esecuzione di dotnet run.To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. L'argomento della riga di comando esegue l'override del valore urls dal file hostsettings.json, mentre il server esegue l'ascolto sulla porta 8080:The command-line argument overrides the urls value from the hostsettings.json file, and the server listens on port 8080:

dotnet run --urls "http://*:8080"

Gestire l'hostManage the host

RunRun

Il metodo Run avvia l'app Web e blocca il thread di chiamata fino all'arresto dell'host:The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

StartStart

Eseguire l'host in modo non bloccante chiamandone il metodo Start:Run the host in a non-blocking manner by calling its Start method:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Se viene passato un elenco di URL al metodo Start, viene eseguito l'ascolto sugli URL specificati:If a list of URLs is passed to the Start method, it listens on the URLs specified:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

L'app può inizializzare e avviare un nuovo host usando i valori predefiniti preconfigurati di CreateDefaultBuilder con un metodo pratico statico.The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a static convenience method. Questi metodi avviano il server senza l'output della console e con l'attesa WaitForShutdown di un'interruzione (Ctrl-C/SIGINT o SIGTERM):These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):

Start(RequestDelegate app)Start(RequestDelegate app)

Start con RequestDelegate:Start with a RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Creare una richiesta nel browser a http://localhost:5000 per ricevere la risposta "Hello World!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, RequestDelegate app)Start(string url, RequestDelegate app)

Start con un URL e RequestDelegate:Start with a URL and RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produce lo stesso risultato di Start(app RequestDelegate) , ad eccezione del fatto che l'app risponde su http://localhost:8080.Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)Start(Action<IRouteBuilder> routeBuilder)

Usare un'istanza di IRouteBuilder (Microsoft.AspNetCore.Routing) per usare il middleware di routing:Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Usare le richieste del browser seguenti con l'esempio:Use the following browser requests with the example:

RichiestaRequest RispostaResponse
http://localhost:5000/hello/Martin Hello, Martin!Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Genera un'eccezione con la stringa "ooops!"Throws an exception with string "ooops!"
http://localhost:5000/throw Genera un'eccezione con la stringa "Uh oh!"Throws an exception with string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!Sante, Kevin!
http://localhost:5000 Hello World!Hello World!

WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, Action<IRouteBuilder> routeBuilder)Start(string url, Action<IRouteBuilder> routeBuilder)

Usare un URL e un'istanza di IRouteBuilder:Use a URL and an instance of IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce lo stesso risultato di Start(Action<IRouteBuilder> routeBuilder) , ad eccezione del fatto che l'app risponde in http://localhost:8080.Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)StartWith(Action<IApplicationBuilder> app)

Specificare un delegato per configurare IApplicationBuilder:Provide a delegate to configure an IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Creare una richiesta nel browser a http://localhost:5000 per ricevere la risposta "Hello World!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown rimane bloccato fino a quando non viene eseguita un'interruzione (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. L'app visualizza il messaggio Console.WriteLine e attende la pressione di un tasto per chiudersi.The app displays the Console.WriteLine message and waits for a keypress to exit.

StartWith(string url, Action<IApplicationBuilder> app)StartWith(string url, Action<IApplicationBuilder> app)

Specificare un URL e un delegato per configurare IApplicationBuilder:Provide a URL and a delegate to configure an IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce lo stesso risultato di StartWith(Action<IApplicationBuilder> app) , ad eccezione del fatto che l'app risponde su http://localhost:8080.Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080.

Interfaccia IHostingEnvironmentIHostingEnvironment interface

L'interfaccia IHostingEnvironment fornisce informazioni sull'ambiente di hosting Web dell'app.The IHostingEnvironment interface provides information about the app's web hosting environment. Usare l'inserimento di un costruttore per ottenere IHostingEnvironment per poterne usare le proprietà e i metodi di estensione:Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

    public CustomFileReader(IHostingEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

È possibile usare un approccio basato su convenzione per configurare l'app all'avvio in base all'ambiente.A convention-based approach can be used to configure the app at startup based on the environment. In alternativa, inserire IHostingEnvironment nel costruttore Startup per l'utilizzo in ConfigureServices:Alternatively, inject the IHostingEnvironment into the Startup constructor for use in ConfigureServices:

public class Startup
{
    public Startup(IHostingEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IHostingEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Nota

Oltre al metodo di estensione IsDevelopment, IHostingEnvironment offre i metodi IsStaging, IsProduction e IsEnvironment(string environmentName).In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.For more information, see Usare più ambienti in ASP.NET Core.

Il servizio IHostingEnvironment può anche essere inserito direttamente nel metodo Configure per configurare la pipeline di elaborazione:The IHostingEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IHostingEnvironment può essere inserito nel metodo Invoke durante la creazione di middleware personalizzato:IHostingEnvironment can be injected into the Invoke method when creating custom middleware:

public async Task Invoke(HttpContext context, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interfaccia IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime consente attività post-avvio e di arresto.IApplicationLifetime allows for post-startup and shutdown activities. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi Action che definiscono gli eventi di avvio e arresto.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token di annullamentoCancellation Token Attivato quando…Triggered when…
ApplicationStartedApplicationStarted L'host è stato completamente avviato.The host has fully started.
ApplicationStoppedApplicationStopped L'host sta completando un arresto normale.The host is completing a graceful shutdown. Tutte le richieste devono essere elaborate.All requests should be processed. L'arresto è bloccato fino al completamento di questo evento.Shutdown blocks until this event completes.
ApplicationStoppingApplicationStopping L'host sta eseguendo un arresto normale.The host is performing a graceful shutdown. È possibile che le richieste siano ancora in esecuzione.Requests may still be processing. L'arresto è bloccato fino al completamento di questo evento.Shutdown blocks until this event completes.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

StopApplication richiede la chiusura dell'applicazione corrente.StopApplication requests termination of the app. La classe seguente usa StopApplication per arrestare normalmente un'app quando viene chiamato il metodo Shutdown della classe:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

Convalida dell'ambitoScope validation

CreateDefaultBuilder imposta ServiceProviderOptions.ValidateScopes su true se l'ambiente dell'app è lo sviluppo.CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development.

Quando ValidateScopes è impostato su true, il provider di servizi predefinito esegue dei controlli per verificare che:When ValidateScopes is set to true, the default service provider performs checks to verify that:

  • I servizi con ambito non vengano risolti direttamente o indirettamente dal provider di servizi radice.Scoped services aren't directly or indirectly resolved from the root service provider.
  • I servizi con ambito non vengano inseriti direttamente o indirettamente in singleton.Scoped services aren't directly or indirectly injected into singletons.

Il provider di servizi radice venga creato con la chiamata di BuildServiceProvider.The root service provider is created when BuildServiceProvider is called. La durata del provider di servizi radice corrisponde alla durata dell'app/server quando il provider viene avviato con l'app e viene eliminato alla chiusura dell'app.The root service provider's lifetime corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app shuts down.

I servizi con ambito vengono eliminati dal contenitore che li ha creati.Scoped services are disposed by the container that created them. Se un servizio con ambito viene creato nel contenitore radice, la durata del servizio viene di fatto convertita in singleton, perché il servizio viene eliminato solo dal contenitore radice alla chiusura dell'app/server.If a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root container when app/server is shut down. La convalida degli ambiti servizio rileva queste situazioni nel contesto della chiamata di BuildServiceProvider.Validating service scopes catches these situations when BuildServiceProvider is called.

Per convalidare sempre gli ambiti, inclusi quelli dell'ambiente di produzione, configurare ServiceProviderOptions con UseDefaultServiceProvider nel generatore di host:To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with UseDefaultServiceProvider on the host builder:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Risorse aggiuntiveAdditional resources