Host generico .NET in ASP.NET Core

Questo articolo fornisce informazioni sull'uso dell'host generico .NET in ASP.NET Core.

I modelli ASP.NET Core creano un WebApplicationBuilder e WebApplication, che offrono un modo semplificato per configurare ed eseguire applicazioni Web senza una Startup classe. Per altre informazioni su WebApplicationBuilder e WebApplication, vedere Eseguire la migrazione da ASP.NET Core 5.0 a 6.0.

Per informazioni sull'uso dell'host generico .NET nelle app console, vedere Host generico .NET.

Definizione host

Un host è un oggetto che incapsula le risorse di un'app, ad esempio:

• Inserimento di dipendenze (DI)
• Registrazione
• Impostazione
• IHostedService Implementazioni

All'avvio, l’host chiama IHostedService.StartAsync ogni implementazione di IHostedService registrata nella raccolta di servizi ospitati del contenitore del servizio. In un'app Web, una delle implementazioni di IHostedService è un servizio web che avvia un'implementazione del server HTTP.

L'inclusione di tutte le risorse interdipendenti dell'app in un oggetto consente il controllo sull'avvio dell'app e sull'arresto normale.

Configurare un host

L'host viene in genere configurato, compilato ed eseguito dal codice in Program.cs. Il codice seguente crea un host con un'implementazione IHostedService aggiunta al contenitore di inserimento delle dipendenze:

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

Per un carico di lavoro HTTP, chiamare ConfigureWebHostDefaults dopo CreateDefaultBuilder:

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

Impostazioni predefinite del generatore

Il metodo CreateDefaultBuilder:

• Imposta la radice del contenuto sul percorso restituito da GetCurrentDirectory.
• Carica la configurazione dell'host da:
  • Le variabili di ambiente con prefisso DOTNET_.
  • Argomenti della riga di comando.
• Carica la configurazione dell'app da:
  • appsettings.json.
  • appsettings.{Environment}.json.
  • Segreti dell'utente quando l'app viene eseguita nell'ambiente Development.
  • variabili di ambiente.
  • Argomenti della riga di comando.
• Aggiunge i provider di registrazione seguenti:
  • Console
  • Debug
  • EventSource
  • EventLog (solo quando è in esecuzione su Windows)
• Abilita la convalida dell'ambito e la convalida delle dipendenze quando l'ambiente è lo sviluppo.

Il metodo ConfigureWebHostDefaults:

• Carica la configurazione host dalle variabili di ambiente precedute da ASPNETCORE_.
• Imposta Kestrel il server come server Web e lo configura usando i provider di configurazione di hosting dell'app. Per le Kestrel opzioni predefinite del server, vedere Configurare le opzioni per il server Web ASP.NET CoreKestrel.
• Aggiunge il middleware dell'applicazione di filtri dell'host.
• Aggiunge il middleware delle intestazioni inoltrate se ASPNETCORE_FORWARDEDHEADERS_ENABLED è uguale a true.
• Abilita l'integrazione di IIS. Per le opzioni predefinite di IIS, vedere Host ASP.NET Core in Windows con IIS.

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.

Servizi forniti dal framework

I servizi seguenti vengono registrati automaticamente:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

Per altre informazioni sui servizi forniti dal framework, vedere Inserimento delle dipendenze in ASP.NET Core.

IHostApplicationLifetime

Inserire il servizio IHostApplicationLifetime (in precedenza IApplicationLifetime) in qualsiasi classe per gestire le attività post-avvio e di arresto normale. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi del gestore dell'evento di avvio e di arresto. L'interfaccia include anche un StopApplication metodo che consente alle app di richiedere un arresto normale.

Quando si esegue un arresto normale, l'host:

• Attiva i ApplicationStopping gestori eventi, che consente all'app di eseguire la logica prima dell'inizio del processo di arresto.
• Arresta il server, che disabilita le nuove connessioni. Il server attende il completamento delle richieste sulle connessioni esistenti, purché il timeout di arresto consenta. Il server invia l'intestazione di chiusura della connessione per ulteriori richieste sulle connessioni esistenti.
• Attiva i ApplicationStopped gestori eventi, che consente all'app di eseguire la logica dopo l'arresto dell'applicazione.

L'esempio seguente è un'implementazione IHostedService che registra i IHostApplicationLifetime gestori eventi:

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

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

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

L'implementazione IHostLifetime controlla quando l'host viene avviato e quando si arresta. Viene usata l'ultima implementazione registrata.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime è l'implementazione IHostLifetime predefinita. ConsoleLifetime:

• Ascolta CTRL+C/SIGINT (Windows), ⌘+C (macOS) o SIGTERM e chiama StopApplication per avviare il processo di arresto.
• Sblocca estensioni come RunAsync e WaitForShutdownAsync.

IHostEnvironment

Inserire il servizio IHostEnvironment in una classe per ottenere informazioni sulle impostazioni seguenti:

• ApplicationName
• EnvironmentName
• ContentRootPath

Le app Web implementano l'interfaccia IWebHostEnvironment , che eredita IHostEnvironment e aggiunge WebRootPath.

Configurazione dell'host

La configurazione dell'host viene usata per le proprietà dell'implementazione IHostEnvironment.

La configurazione host è disponibile all'interno ConfigureAppConfigurationdi HostBuilderContext.Configuration . Dopo ConfigureAppConfiguration, HostBuilderContext.Configuration viene sostituito con la configurazione dell'app.

Per aggiungere la configurazione dell'host, chiamare ConfigureHostConfiguration su IHostBuilder. ConfigureHostConfiguration può essere chiamato più volte e i risultati si sommano. L'host usa l'ultima opzione che imposta un valore in una determinata chiave.

Il provider di variabili di ambiente con prefisso DOTNET_ e argomenti della riga di comando sono inclusi da CreateDefaultBuilder. Per le app Web, viene aggiunto il provider di variabili di ambiente con prefisso ASPNETCORE_. Il prefisso viene rimosso quando vengono lette le variabili di ambiente. Ad esempio, il valore della variabile di ambiente per ASPNETCORE_ENVIRONMENT diventa il valore di configurazione dell'host per la chiave environment.

L'esempio seguente crea la configurazione host:

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

Configurazione dell'app

La configurazione dell'app viene creata chiamando ConfigureAppConfiguration su IHostBuilder. ConfigureAppConfiguration può essere chiamato più volte e i risultati si sommano. L'app usa l'ultima opzione che imposta un valore in una determinata chiave.

La configurazione creata da ConfigureAppConfiguration è disponibile in HostBuilderContext.Configuration per le operazioni successive e come servizio dall'inserimento delle dipendenze. La configurazione dell'host viene aggiunta anche alla configurazione dell'app.

Per altre informazioni, vedere Configurazione in ASP.NET Core.

Impostazioni per tutti i tipi di app

Questa sezione elenca le impostazioni dell'host che si applicano ai carichi di lavoro HTTP e non-HTTP. Per impostazione predefinita, le variabili di ambiente usate per configurare queste impostazioni possono avere un DOTNET_ prefisso o ASPNETCORE_ , che viene visualizzato nell'elenco seguente di impostazioni come {PREFIX_} segnaposto. Per altre informazioni, vedere la sezione Impostazioni del generatore predefinito e Configurazione: Variabili di ambiente.

ApplicationName

La IHostEnvironment.ApplicationName proprietà viene impostata dalla configurazione host durante la costruzione dell'host.

Chiave: applicationName
Tipo: string
Impostazione predefinita: nome dell'assembly che contiene il punto di ingresso dell'app.
Variabile di ambiente: {PREFIX_}APPLICATIONNAME

per impostare questo valore usare la variabile di ambiente.

ContentRoot

La IHostEnvironment.ContentRootPath proprietà determina dove inizia la ricerca dei file di contenuto da parte dell'host. Se il percorso non esiste, l'host non verrà avviato.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: cartella in cui risiede l'assembly dell'app.
Variabile di ambiente: {PREFIX_}CONTENTROOT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseContentRoot su IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

Per altre informazioni, vedi:

• Nozioni fondamentali: radice del contenuto
• WebRoot

EnvironmentName

La IHostEnvironment.EnvironmentName proprietà può essere impostata su qualsiasi valore. I valori definiti dal framework includono Development, Staging e Production. I valori non fanno distinzione tra maiuscole e minuscole.

Chiave: environment
Tipo: string
Predefinito: Production
Variabile di ambiente: {PREFIX_}ENVIRONMENT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseEnvironment su IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout imposta il timeout per StopAsync. Il valore predefinito è 30 secondi. Durante il periodo di timeout, l'host:

• IHostApplicationLifetime.ApplicationStoppingAttiva .
• Tenta di arrestare i servizi ospitati, registrando gli errori per i servizi che non si interrompono.

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. I servizi si arrestano anche se non hanno completato l'elaborazione. Se i servizi richiedono più tempo per l'arresto, aumentare il timeout.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 30 secondi
Variabile di ambiente: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Per impostare questo valore, usare la variabile di ambiente o configurare HostOptions. Nell'esempio seguente il timeout viene impostato su 20 secondi:

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

Disabilitare il ricaricamento della configurazione dell'app in caso di modifica

Per impostazione predefinita, appsettings.json e appsettings.{Environment}.json vengono ricaricati quando il file cambia. Per disabilitare questo comportamento di ricaricamento in ASP.NET Core 5.0 o versione successiva, impostare la hostBuilder:reloadConfigOnChange chiave su false.

Chiave: hostBuilder:reloadConfigOnChange
Tipo: bool (true o false)
Predefinito: true
Argomento della riga di comando: hostBuilder:reloadConfigOnChange
Variabile di ambiente: {PREFIX_}hostBuilder:reloadConfigOnChange

Avviso

Il separatore di due punti (:) non funziona con le chiavi gerarchica delle variabili di ambiente in tutte le piattaforme. Per altre informazioni, vedere Variabili di ambiente.

Impostazioni per le app Web

Alcune impostazioni host si applicano solo ai carichi di lavoro HTTP. Per impostazione predefinita, le variabili di ambiente usate per configurare queste impostazioni possono avere un DOTNET_ prefisso o ASPNETCORE_ , che viene visualizzato nell'elenco seguente di impostazioni come {PREFIX_} segnaposto.

Per queste impostazioni sono disponibili i metodi di estensione su IWebHostBuilder. Gli esempi di codice che illustrano come chiamare i metodi di estensione presumono che webBuilder sia un'istanza di IWebHostBuilder, come nell'esempio seguente:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

Quando è false, gli errori durante l'avvio causano la chiusura dell'host. Quando è true, l'host acquisisce le eccezioni durante l'avvio e tenta di avviare il server.

Chiave: captureStartupErrors
Tipo: bool (true/1 o false/0)
Impostazione predefinita: l'impostazione predefinita è false a meno che l'app non venga eseguita con Kestrel IIS, dove il valore predefinito è true.
Variabile di ambiente: {PREFIX_}CAPTURESTARTUPERRORS

Per impostare questo valore, usare la configurazione o chiamare CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Quando è abilitata o quando l'ambiente è Development, l'app acquisisce gli errori dettagliati.

Chiave: detailedErrors
Tipo: bool (true/1 o false/0)
Predefinito: false
Variabile di ambiente: {PREFIX_}DETAILEDERRORS

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

HostingStartupAssemblies

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da caricare all'avvio. Sebbene il valore di configurazione predefinito sia una stringa vuota, gli assembly di avvio dell'hosting includono sempre l'assembly dell'app. 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.

Chiave: hostingStartupAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Variabile di ambiente: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

HostingStartupExcludeAssemblies

Una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio.

Chiave: hostingStartupExcludeAssemblies
Tipo: string
Impostazione predefinita: stringa vuota
Variabile di ambiente: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

HTTPS_Port

Impostare la porta HTTPS su cui eseguire il reindirizzamento se si ottiene una connessione non HTTPS. Usata per imporre HTTPS. Questa impostazione non causa l'ascolto del server sulla porta specificata. Ciò significa che è possibile reindirizzare accidentalmente le richieste a una porta inutilizzata.

Chiave: https_porttipo: string
Impostazione predefinita: un valore predefinito non è impostato.
Variabile di ambiente: {PREFIX_}HTTPS_PORT

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

HTTPS_Ports

Porte su cui rimanere in ascolto per le connessioni HTTPS.

Chiave: https_ports
Tipo: string
Impostazione predefinita: un valore predefinito non è impostato.
Variabile di ambiente: {PREFIX_}HTTPS_PORTS

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

PreferHostingUrls

Indica se l'host deve essere in ascolto sugli URL configurati con anziché IWebHostBuilder gli URL configurati con l'implementazione IServer .

Chiave: preferHostingUrls
Tipo: bool (true/1 o false/0)
Predefinito: false
Variabile di ambiente: {PREFIX_}PREFERHOSTINGURLS

Per impostare questo valore, usare la variabile di ambiente o chiamare PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Impedisce il caricamento automatico degli assembly di avvio dell'hosting, inclusi gli assembly di avvio dell'hosting configurati dall'assembly dell'app. Per altre informazioni, vedere Usare assembly di avvio dell'hosting in ASP.NET Core.

Chiave: preventHostingStartup
Tipo: bool (true/1 o false/0)
Predefinito: false
Variabile di ambiente: {PREFIX_}PREVENTHOSTINGSTARTUP

Per impostare questo valore, usare la variabile di ambiente o chiamare UseSetting:

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

StartupAssembly

L'assembly per la ricerca della classe Startup.

Chiave: startupAssembly
Tipo: string
Impostazione predefinita: assembly dell'app
Variabile di ambiente: {PREFIX_}STARTUPASSEMBLY

Per impostare questo valore, usare la variabile di ambiente o chiamare UseStartup. UseStartup può richiedere un nome di assembly (string) o un tipo (TStartup). Se vengono chiamati più metodi UseStartup, l'ultimo metodo ha la precedenza.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Se abilitata, elimina l'hosting dei messaggi di stato di avvio.

Chiave: suppressStatusMessages
Tipo: bool (true/1 o false/0)
Predefinito: false
Variabile di ambiente: {PREFIX_}SUPPRESSSTATUSMESSAGES

Per impostare questo valore, usare la configurazione o chiamare UseSetting:

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

URL

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. Ad esempio: http://localhost:123. Usare "*" per indicare che il server deve restare in ascolto delle richieste su qualsiasi indirizzo IP o nome host usando la porta e il protocollo specificati , ad esempio http://*:5000. Il protocollo (http:// o https://) deve essere incluso con ogni URL. I formati supportati variano a seconda del server.

Chiave: urls
Tipo: string
Impostazione predefinita: http://localhost:5000 e https://localhost:5001
Variabile di ambiente: {PREFIX_}URLS

Per impostare questo valore, usare la variabile di ambiente o chiamare UseUrls:

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

Kestrel ha una propria API di configurazione dell'endpoint. Per altre informazioni, vedere Configurare gli endpoint per il server Web ASP.NET CoreKestrel.

WebRoot

La proprietà IWebHostEnvironment.WebRootPath determina il percorso relativo degli asset statici dell'app. Se il percorso non esiste, viene usato un provider di file no-op.

Chiave: webroot
Tipo: string
Impostazione predefinita: il valore predefinito è wwwroot. Il percorso di {content root}/wwwroot deve esistere.
Variabile di ambiente: {PREFIX_}WEBROOT

Per impostare questo valore, usare la variabile di ambiente o chiamare UseWebRoot su IWebHostBuilder:

webBuilder.UseWebRoot("public");

Per altre informazioni, vedi:

• Nozioni fondamentali: radice Web
• ContentRoot

Gestire la durata dell'host

Chiamare metodi sull'implementazione IHost incorporata per avviare e arrestare l'app. Questi metodi influiscono su tutte le IHostedService implementazioni registrate nel contenitore del servizio.

La differenza tra Run* i metodi e Start* è che i metodi attendono il Run* completamento dell'host prima della restituzione, mentre Start* i metodi restituiscono immediatamente. I Run* metodi vengono in genere usati nelle app console, mentre i Start* metodi vengono in genere usati nei servizi a esecuzione prolungata.

Run

Run esegue l'app e blocca il thread di chiamata fino all'arresto dell'host.

RunAsync

RunAsync esegue l'app e restituisce un elemento Task che viene completato quando viene attivato il token di annullamento o l'arresto.

RunConsoleAsync

RunConsoleAsyncabilita il supporto della console, compila e avvia l'host e attende l'arresto di CTRL+C/SIGINT (Windows), ⌘+C (macOS) o SIGTERM.

Inizio

Start avvia l'host in modo sincrono.

StartAsync

StartAsync avvia l'host e restituisce un elemento Task che viene completato quando viene attivato il token di annullamento o l'arresto.

WaitForStartAsync viene chiamato all'avvio di StartAsync, che attende il completamento prima di continuare. Questo metodo può essere usato per ritardare l'avvio fino a quando non viene segnalato da un evento esterno.

StopAsync

StopAsync prova ad arrestare l'host entro il timeout specificato.

WaitForShutdown

WaitForShutdownblocca il thread chiamante finché l'arresto non viene attivato da IHostLifetime, ad esempio tramite CTRL+C/SIGINT (Windows), ⌘+C (macOS) o SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync restituisce un elemento Task che viene completato quando viene attivato l'arresto tramite il token specificato, quindi chiama StopAsync.

Risorse aggiuntive

• Attività in background con servizi ospitati in ASP.NET Core
• Collegamento di GitHub all'origine host generica

  Nota

  I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).