Host generico .NET in ASP.NET Core

Articolo
11/06/2024

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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:

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:

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.

I modelli di ASP.NET Core creano un host generico .NET Core (HostBuilder).

Questo articolo fornisce informazioni sull'uso dell'host generico .NET in ASP.NET Core. Per informazioni sull'uso di 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

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.

Configurare un host

L'host è in genere configurato, compilato ed eseguito da codice nella classe Program. Il metodo Main:

Chiama un metodo CreateHostBuilder per creare e configurare un oggetto generatore.
Chiamate Build e metodi Run nell'oggetto generatore.

I modelli Web ASP.NET Core generano il codice seguente per creare un host:

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

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

Il codice seguente crea un carico di lavoro non HTTP con un'implementazione IHostedService aggiunta al contenitore di inserimento delle dipendenze.

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:

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. Gli strumenti di Entity Framework Core si aspettano di trovare un metodo CreateHostBuilder che configura l'host senza eseguire l'app. Per altre informazioni, vedere Creazione DbContext in fase di progettazione.

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

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

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

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.

L'esempio seguente crea la configurazione host:

// 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'app

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

Impostazioni per tutti i tipi di app

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("c:\\content-root")
    //...

Per altre informazioni, vedi:

EnvironmentName

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 è cinque 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.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 5 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>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

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

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

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

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.

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

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

Porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: 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");

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

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

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

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.

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

webBuilder.UseWebRoot("public");

Per altre informazioni, vedi:

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.

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.

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.

Controllo esterno

Il controllo diretto della durata dell'host può essere ottenuto usando metodi che possono essere chiamati dall'esterno:

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

I modelli di ASP.NET Core creano un host generico .NET Core (HostBuilder).

Questo articolo fornisce informazioni sull'uso dell'host generico .NET in ASP.NET Core. Per informazioni sull'uso di 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

Configurare un host

L'host è in genere configurato, compilato ed eseguito da codice nella classe Program. Il metodo Main:

Chiama un metodo CreateHostBuilder per creare e configurare un oggetto generatore.
Chiamate Build e metodi Run nell'oggetto generatore.

I modelli Web ASP.NET Core generano il codice seguente per creare un host generico:

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

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

Il codice seguente crea un host generico usando un carico di lavoro non HTTP. L'implementazione IHostedService viene aggiunta al contenitore di inserimento delle dipendenze:

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:

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

Il codice precedente viene generato dai modelli ASP.NET Core.

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 Kestrel Server Web in ASP.NET Core.
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

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

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

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.

L'esempio seguente crea la configurazione host:

// 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'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 nella configurazione seguente per il {PREFIX_} segnaposto.

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("c:\\content-root")
    //...

Per altre informazioni, vedi:

EnvironmentName

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 è cinque 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.

Chiave: shutdownTimeoutSeconds
Tipo: int
Impostazione predefinita: 5 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>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

Impostazioni per le app Web

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

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.

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

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

Porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: 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");

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

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

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

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 Kestrel Server Web in ASP.NET Core.

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.

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

webBuilder.UseWebRoot("public");

Per altre informazioni, vedi:

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.

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.

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.

Controllo esterno

Il controllo diretto della durata dell'host può essere ottenuto usando metodi che possono essere chiamati dall'esterno:

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

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

Condividi tramite

Host generico .NET in ASP.NET Core

Definizione host

Configurare un host

Impostazioni predefinite del generatore

Servizi forniti dal framework

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Configurazione dell'host

Configurazione dell'app

Impostazioni per tutti i tipi di app

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

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

Impostazioni per le app Web

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

HTTPS_Ports

PreferHostingUrls

PreventHostingStartup

StartupAssembly

SuppressStatusMessages

URL

WebRoot

Gestire la durata dell'host

Run

RunAsync

RunConsoleAsync

Inizio

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

Definizione host

Configurare un host

Impostazioni predefinite del generatore

Servizi forniti dal framework

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Configurazione dell'host

Configurazione dell'app

Impostazioni per tutti i tipi di app

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

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

Impostazioni per le app Web

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

SuppressStatusMessages

URL

WebRoot

Gestire la durata dell'host

Run

RunAsync

RunConsoleAsync

Inizio

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

Controllo esterno

Definizione host

Configurare un host

Impostazioni predefinite del generatore

Servizi forniti dal framework