Host generico .NET.NET Generic Host

Questo articolo introduce l'host generico .NET Core (HostBuilder) e fornisce indicazioni su come usarlo.This article introduces the .NET Core Generic Host (HostBuilder) and provides guidance on how to use it.

Che cos'è un host?What's a host?

Un host è un oggetto che incapsula le risorse di un'app, ad esempio:A host is an object that encapsulates an app's resources, such as:

  • Inserimento di dipendenze (DI)Dependency injection (DI)
  • RegistrazioneLogging
  • ConfigurazioneConfiguration
  • IHostedService ImplementazioniIHostedService implementations

Quando un host viene avviato, chiama IHostedService.StartAsync in ogni implementazione di IHostedService che trova nel contenitore di inserimento delle dipendenze.When a host starts, it calls IHostedService.StartAsync on each implementation of IHostedService that it finds in the DI container. In un'app Web, una delle implementazioni di IHostedService è un servizio web che avvia un'implementazione del server HTTP.In a web app, one of the IHostedService implementations is a web service that starts an HTTP server implementation.

Il motivo principale per cui tutte le risorse interdipendenti dell'app sono incluse in un unico oggetto è la gestione del ciclo di vita, vale a dire il controllo sull'avvio dell'app e sull'arresto normale.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Nelle versioni di ASP.NET Core precedenti alla 3.0, il Web Host viene usato per i carichi di lavoro HTTP.In versions of ASP.NET Core earlier than 3.0, the Web Host is used for HTTP workloads. L'host Web non è più consigliato per le app Web e resta disponibile solo per compatibilità con le versioni precedenti.The Web Host is no longer recommended for web apps and remains available only for backward compatibility.

Configurare un hostSet up a host

L'host è in genere configurato, compilato ed eseguito da codice nella classe Program.The host is typically configured, built, and run by code in the Program class. Il metodo Main:The Main method:

  • Chiama un metodo CreateHostBuilder per creare e configurare un oggetto generatore.Calls a CreateHostBuilder method to create and configure a builder object.
  • Chiamate Build e metodi Run nell'oggetto generatore.Calls Build and Run methods on the builder object.

Di seguito è riportato il codice Program.cs per un carico di lavoro non HTTP, con un'unica implementazione di IHostedService aggiunta al contenitore di inserimento delle dipendenze.Here's Program.cs code for a non-HTTP workload, with a single IHostedService implementation added to the DI container.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

Per un carico di lavoro HTTP, il metodo Main è lo stesso ma CreateHostBuilder chiama ConfigureWebHostDefaults:For an HTTP workload, the Main method is the same but CreateHostBuilder calls ConfigureWebHostDefaults:

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

Se l'app usa Entity Framework Core, non modificare il nome o la firma del metodo CreateHostBuilder.If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method. Gli strumenti di Entity Framework Core si aspettano di trovare un metodo CreateHostBuilder che configura l'host senza eseguire l'app.The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without running the app. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.For more information, see Design-time DbContext Creation.

Impostazioni predefinite del generatoreDefault builder settings

Il metodo CreateDefaultBuilder:The CreateDefaultBuilder method:

  • Imposta la radice del contenuto sul percorso restituito da GetCurrentDirectory.Sets the content root to the path returned by GetCurrentDirectory.
  • Carica la configurazione dell'host da:Loads host configuration from:
    • Le variabili di ambiente con prefisso "DOTNET_".Environment variables prefixed with "DOTNET_".
    • Argomenti della riga di comando.Command-line arguments.
  • Carica la configurazione dell'app da:Loads app configuration from:
    • appsettings.json.appsettings.json.
    • appsettings.{Environment}.json.appsettings.{Environment}.json.
    • Segreti del manager quando l'app viene eseguita nell'ambiente Development.Secret Manager when the app runs in the Development environment.
    • Variabili di ambiente.Environment variables.
    • Argomenti della riga di comando.Command-line arguments.
  • Aggiunge i provider di log seguenti:Adds the following logging providers:
    • ConsoleConsole
    • DebugDebug
    • EventSourceEventSource
    • EventLog (solo quando è in esecuzione su Windows)EventLog (only when running on Windows)
  • Abilita la convalida dell'ambito e la convalida delle dipendenze quando l'ambiente è lo sviluppo.Enables scope validation and dependency validation when the environment is Development.

Il metodo ConfigureWebHostDefaults:The ConfigureWebHostDefaults method:

Le sezioni Impostazioni per tutti i tipi di app e Impostazioni per le app Web più avanti in questo articolo mostrano come eseguire l'override delle impostazioni predefinite del generatore.The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

Servizi forniti dal frameworkFramework-provided services

I servizi che vengono registrati automaticamente includono:Services that are registered automatically include the following:

Per ulteriori informazioni sui servizi forniti dal Framework, vedere Inserimento delle dipendenze in ASP.NET Core.For more information on framework-provided services, see Inserimento delle dipendenze in ASP.NET Core.

IHostApplicationLifetimeIHostApplicationLifetime

Inserire il servizio IHostApplicationLifetime (in precedenza IApplicationLifetime) in qualsiasi classe per gestire le attività post-avvio e di arresto normale.Inject the IHostApplicationLifetime (formerly IApplicationLifetime) service into any class to handle post-startup and graceful shutdown tasks. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi del gestore dell'evento di avvio e di arresto.Three properties on the interface are cancellation tokens used to register app start and app stop event handler methods. L'interfaccia include anche un metodo StopApplication.The interface also includes a StopApplication method.

L'esempio seguente è un'implementazione di IHostedService che registra gli eventi IHostApplicationLifetime:The following example is an IHostedService implementation that registers IHostApplicationLifetime events:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetimeIHostLifetime

L'implementazione IHostLifetime controlla quando l'host viene avviato e quando si arresta.The IHostLifetime implementation controls when the host starts and when it stops. Viene usata l'ultima implementazione registrata.The last implementation registered is used.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime è l'implementazione IHostLifetime predefinita.Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:ConsoleLifetime:

IHostEnvironmentIHostEnvironment

Inserire il servizio IHostEnvironment in una classe per ottenere informazioni su quanto segue:Inject the IHostEnvironment service into a class to get information about the following:

Le app Web implementano l'interfaccia IWebHostEnvironment, che eredita IHostEnvironment e aggiunge:Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds:

Configurazione dell'hostHost configuration

La configurazione dell'host viene usata per le proprietà dell'implementazione IHostEnvironment.Host configuration is used for the properties of the IHostEnvironment implementation.

La configurazione dell'host è disponibile da HostBuilderContext.Configuration all'interno di ConfigureAppConfiguration.Host configuration is available from HostBuilderContext.Configuration inside ConfigureAppConfiguration. Dopo ConfigureAppConfiguration, HostBuilderContext.Configuration viene sostituito con la configurazione dell'app.After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

Per aggiungere la configurazione dell'host, chiamare ConfigureHostConfiguration su IHostBuilder.To add host configuration, call ConfigureHostConfiguration on IHostBuilder. ConfigureHostConfiguration può essere chiamato più volte e i risultati si sommano.ConfigureHostConfiguration can be called multiple times with additive results. L'host usa l'ultima opzione che imposta un valore in una determinata chiave.The host uses whichever option sets a value last on a given key.

Il provider di variabili di ambiente con prefisso DOTNET_ e gli argomenti della riga di comando vengono inclusi da CreateDefaultBuilder.The environment variable provider with prefix DOTNET_ and command line args are included by CreateDefaultBuilder. Per le app Web, viene aggiunto il provider di variabili di ambiente con prefisso ASPNETCORE_.For web apps, the environment variable provider with prefix ASPNETCORE_ is added. Il prefisso viene rimosso quando vengono lette le variabili di ambiente.The prefix is removed when the environment variables are read. Ad esempio, il valore della variabile di ambiente per ASPNETCORE_ENVIRONMENT diventa il valore di configurazione dell'host per la chiave environment.For example, the environment variable value for ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

L'esempio seguente crea la configurazione host:The following example creates host configuration:

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

Configurazione dell'appApp configuration

La configurazione dell'app viene creata chiamando ConfigureAppConfiguration su IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on IHostBuilder. ConfigureAppConfiguration può essere chiamato più volte e i risultati si sommano.ConfigureAppConfiguration can be called multiple times with additive results. L'app usa l'ultima opzione che imposta un valore in una determinata chiave.The app uses whichever option sets a value last on a given key.

La configurazione creata da ConfigureAppConfiguration è disponibile in HostBuilderContext.Configuration per le operazioni successive e come servizio da DI.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and as a service from DI. La configurazione dell'host viene aggiunta anche alla configurazione dell'app.The host configuration is also added to the app configuration.

Per altre informazioni, vedere Configurazione in ASP.NET Core.For more information, see Configuration in ASP.NET Core.

Impostazioni per tutti i tipi di appSettings for all app types

Questa sezione elenca le impostazioni dell'host che si applicano ai carichi di lavoro HTTP e non-HTTP.This section lists host settings that apply to both HTTP and non-HTTP workloads. Per impostazione predefinita, le variabili di ambiente usate per configurare queste impostazioni possono avere un prefisso DOTNET_ o ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

ApplicationNameApplicationName

La proprietà IHostEnvironment.ApplicationName viene impostata dalla configurazione dell'host durante la costruzione dell'host.The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

Chiave: applicationNameKey: applicationName
Tipo: stringType: string
Impostazione predefinita: il nome dell'assembly che contiene il punto di ingresso dell'app.Default: The name of the assembly that contains the app's entry point. Variabile di ambiente: <PREFIX_>APPLICATIONNAMEEnvironment variable: <PREFIX_>APPLICATIONNAME

per impostare questo valore usare la variabile di ambiente.To set this value, use the environment variable.

ContentRootPathContentRootPath

La proprietà IHostEnvironment.ContentRootPath determina il punto in cui l'host inizia a cercare i file di contenuto.The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. Se il percorso non esiste, l'host non verrà avviato.If the path doesn't exist, the host fails to start.

Chiave: contentRootKey: contentRoot
Tipo: stringType: string
Impostazione predefinita: la cartella in cui risiede l'assembly dell'app.Default: The folder where the app assembly resides.
Variabile di ambiente: <PREFIX_>CONTENTROOTEnvironment variable: <PREFIX_>CONTENTROOT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseContentRoot su IHostBuilder:To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

Per altre informazioni, vedere:For more information, see:

EnvironmentNameEnvironmentName

La proprietà IHostEnvironment.EnvironmentName può essere impostata su qualsiasi valore.The IHostEnvironment.EnvironmentName property 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.

Chiave: environmentKey: environment
Tipo: stringType: string
Impostazione predefinita: ProductionDefault: Production
Variabile di ambiente: <PREFIX_>ENVIRONMENTEnvironment variable: <PREFIX_>ENVIRONMENT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseEnvironment su IHostBuilder:To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeoutShutdownTimeout

HostOptions.ShutdownTimeout imposta il timeout per StopAsync.HostOptions.ShutdownTimeout sets the timeout for StopAsync. Il valore predefinito è cinque secondi.The default value is five seconds. Durante il periodo di timeout, l'host:During the timeout period, the host:

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.

Chiave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Valore predefinito: 5 secondi variabile di ambiente: <PREFIX_>SHUTDOWNTIMEOUTSECONDSDefault: 5 seconds Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

Per impostare questo valore, usare la variabile di ambiente o configurare HostOptions.To set this value, use the environment variable or configure HostOptions. Nell'esempio seguente il timeout viene impostato su 20 secondi:The following example sets the timeout to 20 seconds:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Impostazioni per le app WebSettings for web apps

Alcune impostazioni host si applicano solo ai carichi di lavoro HTTP.Some host settings apply only to HTTP workloads. Per impostazione predefinita, le variabili di ambiente usate per configurare queste impostazioni possono avere un prefisso DOTNET_ o ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

Per queste impostazioni sono disponibili i metodi di estensione su IWebHostBuilder.Extension methods on IWebHostBuilder are available for these settings. Gli esempi di codice che illustrano come chiamare i metodi di estensione presumono che webBuilder sia un'istanza di IWebHostBuilder, come nell'esempio seguente:Code samples that show how to call the extension methods assume webBuilder is an instance of IWebHostBuilder, as in the following example:

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

CaptureStartupErrorsCaptureStartupErrors

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.

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.
Variabile di ambiente: <PREFIX_>CAPTURESTARTUPERRORSEnvironment variable: <PREFIX_>CAPTURESTARTUPERRORS

Per impostare questo valore, usare la configurazione o chiamare CaptureStartupErrors:To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrorsDetailedErrors

Quando è abilitata o quando l'ambiente è Development, l'app acquisisce gli errori dettagliati.When enabled, or when the environment is Development, the app captures detailed errors.

Chiave: detailedErrorsKey: detailedErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Impostazione predefinita: falseDefault: false
Variabile di ambiente: <PREFIX_>_DETAILEDERRORSEnvironment variable: <PREFIX_>_DETAILEDERRORS

Per impostare questo valore, usare la configurazione o chiamare UseSetting:To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssembliesHostingStartupAssemblies

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.

Chiave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: stringType: string
Impostazione predefinita: stringa vuotaDefault: Empty string
Variabile di ambiente: <PREFIX_>_HOSTINGSTARTUPASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

Per impostare questo valore, usare la configurazione o chiamare UseSetting:To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssembliesHostingStartupExcludeAssemblies

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
Variabile di ambiente: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Per impostare questo valore, usare la configurazione o chiamare UseSetting:To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_PortHTTPS_Port

Porta di reindirizzamento HTTPS.The HTTPS redirect port. Usata per imporre HTTPS.Used in enforcing HTTPS.

Chiave: https_portKey: https_port
Tipo: stringType: string
Impostazione predefinita: un valore predefinito non è impostato.Default: A default value isn't set.
Variabile di ambiente: <PREFIX_>HTTPS_PORTEnvironment variable: <PREFIX_>HTTPS_PORT

Per impostare questo valore, usare la configurazione o chiamare UseSetting:To set this value, use configuration or call UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrlsPreferHostingUrls

Indica se l'host deve eseguire l'ascolto sugli URL configurati con IWebHostBuilder anziché su quelli configurati con l'implementazione IServer.Indicates whether the host should listen on the URLs configured with the IWebHostBuilder 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
Variabile di ambiente: <PREFIX_>_PREFERHOSTINGURLSEnvironment variable: <PREFIX_>_PREFERHOSTINGURLS

Per impostare questo valore, usare la variabile di ambiente o chiamare PreferHostingUrls:To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartupPreventHostingStartup

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 ulteriori 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
Variabile di ambiente: <PREFIX_>_PREVENTHOSTINGSTARTUPEnvironment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

Per impostare questo valore, usare la variabile di ambiente o chiamare UseSetting:To set this value, use the environment variable or call UseSetting :

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssemblyStartupAssembly

L'assembly per la ricerca della classe Startup.The assembly to search for the Startup class.

Chiave: startupAssemblyKey: startupAssembly
Tipo: stringType: string
Impostazione predefinita: assembly dell'appDefault: The app's assembly
Variabile di ambiente: <PREFIX_>STARTUPASSEMBLYEnvironment variable: <PREFIX_>STARTUPASSEMBLY

Per impostare questo valore, usare la variabile di ambiente o chiamare UseStartup.To set this value, use the environment variable or call UseStartup. UseStartup può richiedere un nome di assembly (string) o un tipo (TStartup).UseStartup can take an assembly name (string) or a type (TStartup). Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.If multiple UseStartup methods are called, the last one takes precedence.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

URLURLs

Elenco delimitato da punto e virgola degli indirizzi IP o gli indirizzi host con le porte e protocolli su cui il server deve eseguire l'ascolto per le richieste.A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should listen on for requests. 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.

Chiave: urlsKey: urls
Tipo: stringType: string
Impostazione predefinita: http://localhost:5000 e https://localhost:5001Default: http://localhost:5000 and https://localhost:5001
Variabile di ambiente: <PREFIX_>URLSEnvironment variable: <PREFIX_>URLS

Per impostare questo valore, usare la variabile di ambiente o chiamare UseUrls:To set this value, use the environment variable or call UseUrls:

webBuilder.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 ulteriori informazioni, vedere Implementazione del server Web Kestrel in ASP.NET Core.For more information, see Implementazione del server Web Kestrel in ASP.NET Core.

WebRootWebRoot

Il percorso relativo degli asset statici dell'app.The relative path to the app's static assets.

Chiave: webrootKey: webroot
Tipo: stringType: string
Impostazione predefinita: il valore predefinito è wwwroot.Default: The default is wwwroot. Il percorso di {radice del contenuto}/wwwroot deve esistere.The path to {content root}/wwwroot must exist. Se il percorso non esiste, viene usato un provider di file no-op.If the path doesn't exist, a no-op file provider is used.
Variabile di ambiente: <PREFIX_>WEBROOTEnvironment variable: <PREFIX_>WEBROOT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseWebRoot:To set this value, use the environment variable or call UseWebRoot:

webBuilder.UseWebRoot("public");

Per altre informazioni, vedere:For more information, see:

Gestire la durata dell'hostManage the host lifetime

Chiamare metodi sull'implementazione IHost incorporata per avviare e arrestare l'app.Call methods on the built IHost implementation to start and stop the app. Questi metodi influiscono su tutte le implementazioni IHostedService che vengono registrate nel contenitore dei servizi.These methods affect all IHostedService implementations that are registered in the service container.

EseguiRun

Run esegue l'app e blocca il thread di chiamata fino all'arresto dell'host.Run runs the app and blocks the calling thread until the host is shut down.

RunAsyncRunAsync

RunAsync esegue l'app e restituisce un elemento Task che viene completato quando viene attivato il token di annullamento o l'arresto.RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered.

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync abilita il supporto della console, compila e avvia l'host e resta in ascolto di CTRL+C/SIGINT o SIGTERM per eseguire l'arresto.RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

InizioStart

Start avvia l'host in modo sincrono.Start starts the host synchronously.

StartAsyncStartAsync

StartAsync avvia l'host e restituisce un elemento Task che viene completato quando viene attivato il token di annullamento o l'arresto.StartAsync starts the host and returns a Task that completes when the cancellation token or shutdown is triggered.

WaitForStartAsync viene chiamato all'avvio di StartAsync, che attende il completamento prima di continuare.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. Questo è utile per ritardare l'avvio fino al segnale trasmesso da un evento esterno.This can be used to delay startup until signaled by an external event.

StopAsyncStopAsync

StopAsync prova ad arrestare l'host entro il timeout specificato.StopAsync attempts to stop the host within the provided timeout.

WaitForShutdownWaitForShutdown

WaitForShutdown blocca il thread chiamante finché non viene attivato l'arresto da IHostLifetime, ad esempio tramite Ctrl + C/SIGINT o SIGTERM.WaitForShutdown blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via Ctrl+C/SIGINT or SIGTERM.

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync restituisce un elemento Task che viene completato quando viene attivato l'arresto tramite il token specificato, quindi chiama StopAsync.WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

Controllo esternoExternal control

Il controllo diretto della durata dell'host può essere ottenuto usando metodi che possono essere chiamati dall'esterno:Direct control of the host lifetime can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

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.

Questo articolo illustra l'host generico di ASP.NET Core (HostBuilder), che si usa per le app che non elaborano le richieste HTTP.This article covers the ASP.NET Core Generic Host (HostBuilder), which is used for apps that don't process HTTP requests.

Lo scopo dell'host generico è separare la pipeline HTTP dall'API dell'host Web, per abilitare una gamma più ampia di scenari host.The purpose of Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of host scenarios. La messaggistica, le attività in background e altri carichi di lavoro non HTTP basati sull'host generico traggono vantaggio dalle funzionalità a montaggio incrociato come la configurazione, l'inserimento di dipendenze (DI) e la registrazione.Messaging, background tasks, and other non-HTTP workloads based on Generic Host benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

L'host generico è una nuova funzionalità introdotta in ASP.NET Core 2.1 e non è adatto agli scenari di hosting Web.Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. Per gli scenari di hosting Web usare l'host Web.For web hosting scenarios, use the Web Host. L'host generico sostituirà l'host Web in una versione futura, funzionando come API host principale negli scenari sia HTTP che non HTTP.Generic Host will replace Web Host in a future release and act as the primary host API in both HTTP and non-HTTP scenarios.

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

Quando si esegue l'app di esempio in Visual Studio Code, usare un terminale esterno o integrato.When running the sample app in Visual Studio Code, use an external or integrated terminal. Non eseguire l'esempio in un ambiente internalConsole.Don't run the sample in an internalConsole.

Per impostare la console in Visual Studio Code:To set the console in Visual Studio Code:

  1. Aprire il file .vscode/launch.json.Open the .vscode/launch.json file.
  2. Nella configurazione .NET Core Launch (console) trovare la voce console.In the .NET Core Launch (console) configuration, locate the console entry. Impostare il valore su externalTerminal o integratedTerminal.Set the value to either externalTerminal or integratedTerminal.

IntroduzioneIntroduction

La libreria host generico è disponibile nello spazio dei nomi Microsoft.Extensions.Hosting e viene specificata dal pacchetto Microsoft.Extensions.Hosting.The Generic Host library is available in the Microsoft.Extensions.Hosting namespace and provided by the Microsoft.Extensions.Hosting package. Il pacchetto Microsoft.Extensions.Hosting è incluso nel metapacchetto Microsoft.AspNetCore.App (ASP.NET Core 2.1 o versioni successive).The Microsoft.Extensions.Hosting package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

IHostedService è il punto di ingresso per l'esecuzione del codice.IHostedService is the entry point to code execution. Ogni implementazione IHostedService viene eseguita nell'ordine di registrazione del servizio in ConfigureServices.Each IHostedService implementation is executed in the order of service registration in ConfigureServices. StartAsync viene chiamato su ogni IHostedService quando viene avviato l'host e StopAsync viene chiamato in ordine di registrazione inverso quando l'host viene chiuso normalmente.StartAsync is called on each IHostedService when the host starts, and StopAsync is called in reverse registration order when the host shuts down gracefully.

Configurare un hostSet up a host

IHostBuilder è il componente principale che le librerie e le app usano per inizializzare, compilare ed eseguire l'host:IHostBuilder is the main component that libraries and apps use to initialize, build, and run the host:

public static async Task Main(string[] args)
{
    var host = new HostBuilder()
        .Build();

    await host.RunAsync();
}

OpzioniOptions

HostOptions configura le opzioni per IHost.HostOptions configure options for the IHost.

Timeout di arrestoShutdown timeout

ShutdownTimeout imposta il timeout per StopAsync.ShutdownTimeout sets the timeout for StopAsync. Il valore predefinito è cinque secondi.The default value is five seconds.

La configurazione delle opzioni seguenti in Program.Main aumenta il timeout di arresto di cinque secondi a 20 secondi:The following option configuration in Program.Main increases the default five second shutdown timeout to 20 seconds:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

Servizi predefinitiDefault services

I servizi seguenti vengono registrati durante l'inizializzazione dell'host:The following services are registered during host initialization:

Configurazione dell'hostHost configuration

La configurazione dell'host viene creata tramite:Host configuration is created by:

Metodi di estensioneExtension methods

Chiave applicazione (nome)Application key (name)

La proprietà IHostingEnvironment.ApplicationName viene impostata dalla configurazione dell'host durante la costruzione dell'host.The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. Per impostare il valore in modo esplicito, usare HostDefaults.ApplicationKey:To set the value explicitly, use the HostDefaults.ApplicationKey:

Chiave: applicationNameKey: applicationName
Tipo: stringType: string
Impostazione predefinita: il nome dell'assembly contenente il punto di ingresso dell'app.Default: The name of the assembly containing the app's entry point.
Impostare usando: HostBuilderContext.HostingEnvironment.ApplicationNameSet using: HostBuilderContext.HostingEnvironment.ApplicationName
Variabile di ambiente: <PREFIX_>APPLICATIONNAME (<PREFIX_> è facoltativo e definito dall'utente)Environment variable: <PREFIX_>APPLICATIONNAME (<PREFIX_> is optional and user-defined)

Radice del contenutoContent root

Questa impostazione determina la posizione da cui l'host inizia la ricerca dei file di contenuto.This setting determines where the host begins searching for content files.

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: <PREFIX_>CONTENTROOT (<PREFIX_> è facoltativo e definito dall'utente)Environment variable: <PREFIX_>CONTENTROOT (<PREFIX_> is optional and user-defined)

Se il percorso non esiste, l'host non verrà avviato.If the path doesn't exist, the host fails to start.

var host = new HostBuilder()
    .UseContentRoot("c:\\<content-root>")

Per altre informazioni, vedere nozioni fondamentali: radice del contenuto.For more information, see Fundamentals: Content root.

AmbienteEnvironment

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

Chiave: environmentKey: environment
Tipo: stringType: string
Impostazione predefinita: ProductionDefault: Production
Impostare usando: UseEnvironmentSet using: UseEnvironment
Variabile di ambiente: <PREFIX_>ENVIRONMENT (<PREFIX_> è facoltativo e definito dall'utente)Environment variable: <PREFIX_>ENVIRONMENT (<PREFIX_> is optional and user-defined)

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.

var host = new HostBuilder()
    .UseEnvironment(EnvironmentName.Development)

ConfigureHostConfigurationConfigureHostConfiguration

ConfigureHostConfiguration usa un'interfaccia IConfigurationBuilder per creare un'interfaccia IConfiguration per l'host.ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. La configurazione dell'host viene usata per inizializzare l'interfaccia IHostingEnvironment da usare nel processo di compilazione dell'app.The host configuration is used to initialize the IHostingEnvironment for use in the app's build process.

ConfigureHostConfiguration può essere chiamato più volte e i risultati si sommano.ConfigureHostConfiguration can be called multiple times with additive results. L'host usa l'ultima opzione che imposta un valore in una determinata chiave.The host uses whichever option sets a value last on a given key.

Nessun provider è incluso per impostazione predefinita.No providers are included by default. È necessario specificare in modo esplicito tutti i provider di configurazione richiesti dall'app in ConfigureHostConfiguration, inclusi:You must explicitly specify whatever configuration providers the app requires in ConfigureHostConfiguration, including:

  • Configurazione dei file (ad esempio, da un file hostsettings.json).File configuration (for example, from a hostsettings.json file).
  • Configurazione delle variabili di ambiente.Environment variable configuration.
  • Configurazione degli argomenti della riga di comando.Command-line argument configuration.
  • Tutti gli altri provider di configurazione necessari.Any other required configuration providers.

La configurazione file dell'host viene abilitata specificando il percorso di base dell'app con SetBasePath seguito da una chiamata a uno dei provider di configurazione dei file.File configuration of the host is enabled by specifying the app's base path with SetBasePath followed by a call to one of the file configuration providers. L'app di esempio usa un file JSON, hostsettings.json, e chiama AddJsonFile per utilizzare le impostazioni di configurazione host del file.The sample app uses a JSON file, hostsettings.json, and calls AddJsonFile to consume the file's host configuration settings.

Per aggiungere la configurazione delle variabili di ambiente dell'host, chiamare AddEnvironmentVariables sul generatore di host.To add environment variable configuration of the host, call AddEnvironmentVariables on the host builder. AddEnvironmentVariables accetta un prefisso facoltativo definito dall'utente.AddEnvironmentVariables accepts an optional user-defined prefix. L'app di esempio usa un prefisso di PREFIX_.The sample app uses a prefix of PREFIX_. Il prefisso viene rimosso quando vengono lette le variabili di ambiente.The prefix is removed when the environment variables are read. Quando viene configurato l'host dell'app di esempio, il valore della variabile di ambiente per PREFIX_ENVIRONMENT diventa il valore di configurazione dell'host per la chiave environment.When the sample app's host is configured, the environment variable value for PREFIX_ENVIRONMENT becomes the host configuration value for the environment key.

Durante lo sviluppo quando si usa Visual Studio o si esegue un'app con dotnet run, le variabili di ambiente possono essere impostate nel file Properties/launchSettings.json.During development when using Visual Studio or running an app with dotnet run, environment variables may be set in the Properties/launchSettings.json file. Durante lo sviluppo in Visual Studio Code, le variabili di ambiente possono essere impostate nel file .vscode/launch.json.In Visual Studio Code, environment variables may be set in the .vscode/launch.json file during development. Per ulteriori informazioni, vedere Usare più ambienti in ASP.NET Core.For more information, see Usare più ambienti in ASP.NET Core.

La configurazione della riga di comando viene aggiunta chiamando AddCommandLine.Command-line configuration is added by calling AddCommandLine. La configurazione della riga di comando viene aggiunta per ultima per consentire agli argomenti della riga di comando di eseguire l'override della configurazione fornita dai provider di configurazione precedenti.Command-line configuration is added last to permit command-line arguments to override configuration provided by the earlier configuration providers.

hostsettings.json:hostsettings.json:

{
  "environment": "Development"
}

È possibile fornire una configurazione aggiuntiva con le chiavi applicationName e contentRoot.Additional configuration can be provided with the applicationName and contentRoot keys.

Configurazione di esempio di HostBuilder che usa ConfigureHostConfiguration:Example HostBuilder configuration using ConfigureHostConfiguration:

var host = new HostBuilder()
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    })

ConfigureAppConfigurationConfigureAppConfiguration

La configurazione dell'app viene creata chiamando ConfigureAppConfiguration sull'implementazione IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on the IHostBuilder implementation. ConfigureAppConfiguration usa un'interfaccia IConfigurationBuilder per creare un'interfaccia IConfiguration per l'app.ConfigureAppConfiguration uses an IConfigurationBuilder to create an IConfiguration for the app. ConfigureAppConfiguration può essere chiamato più volte e i risultati si sommano.ConfigureAppConfiguration can be called multiple times with additive results. L'app usa l'ultima opzione che imposta un valore in una determinata chiave.The app uses whichever option sets a value last on a given key. La configurazione creata da ConfigureAppConfiguration è disponibile in HostBuilderContext.Configuration per le operazioni successive e in Services.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and in Services.

La configurazione dell'app riceve automaticamente la configurazione dell'host fornita da ConfigureHostConfiguration.App configuration automatically receives host configuration provided by ConfigureHostConfiguration.

Configurazione app di esempio che usa ConfigureAppConfiguration:Example app configuration using ConfigureAppConfiguration:

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.json:appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

appsettings.Production.json:appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Error",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

Per spostare i file delle impostazioni nella directory di output, specificare i file delle impostazioni come elementi di progetto MSBuild nel file di progetto.To move settings files to the output directory, specify the settings files as MSBuild project items in the project file. L'app di esempio sposta i file delle impostazioni dell'app JSON e hostsettings.json con l'elemento <Content> seguente:The sample app moves its JSON app settings files and hostsettings.json with the following <Content> item:

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Nota

I metodi di estensione di configurazione, ad esempio AddJsonFile e AddEnvironmentVariables, necessitano di altri pacchetti NuGet, ad esempio Microsoft.Extensions.Configuration.Json e Microsoft.Extensions.Configuration.EnvironmentVariables.Configuration extension methods, such as AddJsonFile and AddEnvironmentVariables require additional NuGet packages, such as Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Configuration.EnvironmentVariables. A meno che l'app non usi il metapacchetto Microsoft.AspNetCore.App, questi pacchetti devono essere aggiunti al progetto oltre al pacchetto Microsoft.Extensions.Configuration di base.Unless the app uses the Microsoft.AspNetCore.App metapackage, these packages must be added to the project in addition to the core Microsoft.Extensions.Configuration package. Per ulteriori informazioni, vedere Configurazione in ASP.NET Core.For more information, see Configurazione in ASP.NET Core.

ConfigureServicesConfigureServices

ConfigureServices aggiunge servizi al contenitore di inserimento delle dipendenze dell'app.ConfigureServices adds services to the app's dependency injection container. ConfigureServices può essere chiamato più volte e i risultati si sommano.ConfigureServices can be called multiple times with additive results.

Un servizio ospitato è una classe con logica di attività in background che implementa l'interfaccia IHostedService.A hosted service is a class with background task logic that implements the IHostedService interface. Per ulteriori informazioni, vedere Attività in background con servizi ospitati in ASP.NET Core.For more information, see Attività in background con servizi ospitati in ASP.NET Core.

L'app di esempio usa il metodo di estensione AddHostedService per aggiungere all'app un servizio per gli eventi di durata (LifetimeEventsHostedService) e un'attività in background con timeout (TimedHostedService):The sample app uses the AddHostedService extension method to add a service for lifetime events, LifetimeEventsHostedService, and a timed background task, TimedHostedService, to the app:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLoggingConfigureLogging

ConfigureLogging aggiunge un delegato per configurare l'interfaccia ILoggingBuilder fornita.ConfigureLogging adds a delegate for configuring the provided ILoggingBuilder. ConfigureLogging può essere chiamato più volte e i risultati si sommano.ConfigureLogging may be called multiple times with additive results.

var host = new HostBuilder()
    .ConfigureLogging((hostContext, configLogging) =>
    {
        configLogging.AddConsole();
        configLogging.AddDebug();
    })

UseConsoleLifetimeUseConsoleLifetime

UseConsoleLifetime resta in ascolto di CTRL+C/SIGINT o SIGTERM e chiama StopApplication per avviare il processo di arresto.UseConsoleLifetime listens for Ctrl+C/SIGINT or SIGTERM and calls StopApplication to start the shutdown process. UseConsoleLifetime sblocca estensioni come RunAsync e WaitForShutdownAsync.UseConsoleLifetime unblocks extensions such as RunAsync and WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime è preregistrata come implementazione di durata predefinita.Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is pre-registered as the default lifetime implementation. Viene usata l'ultima durata registrata.The last lifetime registered is used.

var host = new HostBuilder()
    .UseConsoleLifetime()

Configurazione contenitoreContainer configuration

Per supportare l'inserimento di altri contenitori, l'host può accettare un elemento IServiceProviderFactory<TContainerBuilder>.To support plugging in other containers, the host can accept an IServiceProviderFactory<TContainerBuilder>. La disponibilità di una factory non fa parte della registrazione del contenitore DI, ma è una funzionalità intrinseca dell'host usata per creare il contenitore DI concreto.Providing a factory isn't part of the DI container registration but is instead a host intrinsic used to create the concrete DI container. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) esegue l'override della factory predefinita usata per la creazione del provider di servizi dell'app.UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to create the app's service provider.

La configurazione del contenitore personalizzato è gestita dal metodo ConfigureContainer.Custom container configuration is managed by the ConfigureContainer method. ConfigureContainer offre un'esperienza fortemente tipizzata per la configurazione del contenitore sulla base dell'API host sottostante.ConfigureContainer provides a strongly-typed experience for configuring the container on top of the underlying host API. ConfigureContainer può essere chiamato più volte e i risultati si sommano.ConfigureContainer can be called multiple times with additive results.

Creare un contenitore di servizi per l'app:Create a service container for the app:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Specificare una factory per il contenitore di servizi:Provide a service container factory:

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

Usare la factory e configurare il contenitore di servizi personalizzato per l'app:Use the factory and configure the custom service container for the app:

var host = new HostBuilder()
    .UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
    .ConfigureContainer<ServiceContainer>((hostContext, container) =>
    {
    })

ExtensibilityExtensibility

L'estensibilità host viene eseguita con i metodi di estensione su IHostBuilder.Host extensibility is performed with extension methods on IHostBuilder. L'esempio seguente illustra come un metodo di estensione estende un'implementazione IHostBuilder con l'esempio TimedHostedService dimostrato in Attività in background con servizi ospitati in ASP.NET Core.The following example shows how an extension method extends an IHostBuilder implementation with the TimedHostedService example demonstrated in Attività in background con servizi ospitati in ASP.NET Core.

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

Un'app stabilisce il metodo di estensione UseHostedService per registrare il servizio ospitato passato in T:An app establishes the UseHostedService extension method to register the hosted service passed in T:

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

Gestire l'hostManage the host

L'implementazione IHost è responsabile dell'avvio e arresto delle implementazioni IHostedService che sono registrate nel contenitore di servizi.The IHost implementation is responsible for starting and stopping the IHostedService implementations that are registered in the service container.

EseguiRun

Run esegue l'app e blocca il thread di chiamata fino all'arresto dell'host:Run runs the app and blocks the calling thread until the host is shut down:

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

RunAsyncRunAsync

RunAsync esegue l'app e restituisce un elemento Task che viene completato quando viene attivato il token di annullamento o l'arresto:RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered:

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync abilita il supporto della console, compila e avvia l'host e resta in ascolto di CTRL+C/SIGINT o SIGTERM per eseguire l'arresto.RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Start e StopAsyncStart and StopAsync

Start avvia l'host in modo sincrono.Start starts the host synchronously.

StopAsync prova ad arrestare l'host entro il timeout specificato.StopAsync attempts to stop the host within the provided timeout.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync e StopAsyncStartAsync and StopAsync

StartAsync avvia l'app.StartAsync starts the app.

StopAsync arresta l'app.StopAsync stops the app.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdownWaitForShutdown

WaitForShutdown viene attivato tramite IHostLifetime, ad esempio Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (in ascolto di CTRL+C/SIGINT o SIGTERM).WaitForShutdown is triggered via the IHostLifetime, such as Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (listens for Ctrl+C/SIGINT or SIGTERM). WaitForShutdown chiama StopAsync.WaitForShutdown calls StopAsync.

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync restituisce un elemento Task che viene completato quando viene attivato l'arresto tramite il token specificato, quindi chiama StopAsync.WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

Controllo esternoExternal control

Il controllo esterno dell'host può essere ottenuto usando metodi che possono essere chiamati dall'esterno:External control of the host can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

WaitForStartAsync viene chiamato all'avvio di StartAsync, che attende il completamento prima di continuare.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. Questo è utile per ritardare l'avvio fino al segnale trasmesso da un evento esterno.This can be used to delay startup until signaled by an external event.

Interfaccia IHostingEnvironmentIHostingEnvironment interface

IHostingEnvironment include informazioni sull'ambiente di hosting dell'app.IHostingEnvironment provides information about the app's 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 MyClass
{
    private readonly IHostingEnvironment _env;

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

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

Per ulteriori informazioni, vedere Usare più ambienti in ASP.NET Core.For more information, see Usare più ambienti in ASP.NET Core.

Interfaccia IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime consente attività post-avvio e di arresto, incluse le richieste di arresto normale.IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. 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…
ApplicationStarted L'host è stato completamente avviato.The host has fully started.
ApplicationStopped 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.
ApplicationStopping 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.

Inserire tramite costruttore il servizio IApplicationLifetime in qualsiasi classe.Constructor-inject the IApplicationLifetime service into any class. L'app di esempio usa l'inserimento di costruttori in una classe LifetimeEventsHostedService (implementazione IHostedService) per registrare gli eventi.The sample app uses constructor injection into a LifetimeEventsHostedService class (an IHostedService implementation) to register the events.

LifetimeEventsHostedService.cs:LifetimeEventsHostedService.cs:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

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

Risorse aggiuntiveAdditional resources