Host generico .NET in ASP.NET Core

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

In questo argomento vengono fornite informazioni sull'uso dell'host generico .NET in ASP.NET Core. 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
  • Configurazione
  • IHostedService Implementazioni

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

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 ASP.NET Core Web 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 IHostedService un'implementazione aggiunta al contenitore DI.

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:
    • Variabili di ambiente precedute da 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 log 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:

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:

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 metodo StopApplication.

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

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:

IHostEnvironment

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

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

Configurazione dell'host

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

La configurazione dell'host è disponibile da HostBuilderContext.Configuration all'interno di ConfigureAppConfiguration. 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 e argomenti DOTNET_ della riga di comando è incluso 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:

// 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 delle 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 da DI. 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 prefisso DOTNET_ o ASPNETCORE_. Per altre informazioni, vedere la sezione Impostazioni predefinite del generatore.

ApplicationName

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

Chiave: applicationName
Tipo: string
Valore predefinito: 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 proprietà IHostEnvironment.ContentRootPath determina il punto in cui l'host inizia a cercare i file di contenuto. Se il percorso non esiste, l'host non verrà avviato.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: cartella in cui si trova 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, vedere:

EnvironmentName

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

Chiave: environment
Tipo: string
Impostazione predefinita: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:

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 l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.

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 base alle modifiche

Per impostazione predefinita, appsettings.json e appsettings.{ Environment}.json viene ricaricato quando il file viene modificato. 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 ( o true 1 )
Impostazione predefinita:true
Argomento della riga di comando: hostBuilder:reloadConfigOnChange
Variabile di ambiente: <PREFIX_>hostBuilder:reloadConfigOnChange

Avviso

Il separatore dei due punti ( ) non funziona con le chiavi gerarchiche 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 prefisso DOTNET_ o ASPNETCORE_.

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:

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.

Chiave: captureStartupErrors
Tipo: bool ( o true 1 )
Impostazione predefinita: l'impostazione predefinita è , a meno che false l'app non venga eseguita con Kestrel dietro 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 ( o true 1 )
Impostazione predefinita: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

Porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: string
Impostazione predefinita: non è impostato un valore predefinito.
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 restare in ascolto sugli URL configurati con anziché IWebHostBuilder sugli URL configurati con l'implementazione IServer .

Chiave: preferHostingUrls
Tipo: bool ( o true 1 )
Impostazione predefinita:true
Variabile di ambiente: <PREFIX_>_PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(false);

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 ( o true 1 )
Impostazione predefinita: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>();

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 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). 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 la propria API di configurazione dell'endpoint. Per altre informazioni, vedere Configurare gli endpoint per il ASP.NET Core Kestrel Web.

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, vedere:

Gestire la durata dell'host

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

Esegui

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 o SIGTERM.

Avvio

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 è utile per ritardare l'avvio fino al segnale trasmesso 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 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 ASP.NET Core seguenti creano un host generico .NET Core ( HostBuilder ).

Questo argomento fornisce informazioni sull'uso dell'host generico .NET in ASP.NET Core. Per informazioni sull'uso dell'host generico .NET nelle app console, vedere Host generico .NET.

Definizione dell'host

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

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

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

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 ASP.NET Core Web 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. IHostedServiceL'implementazione viene aggiunta al contenitore DI:

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

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:
    • Variabili di ambiente precedute da 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 log 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:

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:

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 metodo StopApplication.

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

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:

IHostEnvironment

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

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

Configurazione dell'host

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

La configurazione dell'host è disponibile da HostBuilderContext.Configuration all'interno di ConfigureAppConfiguration. 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 DOTNET_ prefisso e argomenti della riga di comando è incluso 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:

// 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 delle 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 da DI. 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 prefisso DOTNET_ o ASPNETCORE_.

ApplicationName

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

Chiave: applicationName
Tipo: string
Default: 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 proprietà IHostEnvironment.ContentRootPath determina il punto in cui l'host inizia a cercare i file di contenuto. Se il percorso non esiste, l'host non verrà avviato.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: la cartella in cui si trova 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, vedere:

EnvironmentName

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

Chiave: environment
Tipo: string
Impostazione predefinita: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:

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 l'arresto dei servizi richiede più tempo, aumentare il valore di timeout.

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

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 prefisso DOTNET_ o ASPNETCORE_.

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:

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.

Chiave: captureStartupErrors
Tipo: bool ( o true 1 )
Impostazione predefinita: l'impostazione predefinita è , a meno che false l'app non venga eseguita con Kestrel dietro 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 ( o true 1 )
Impostazione predefinita: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

Porta di reindirizzamento HTTPS. Usata per imporre HTTPS.

Chiave: https_port
Tipo: string
Impostazione predefinita: non è impostato un valore predefinito.
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 restare in ascolto sugli URL configurati con anziché IWebHostBuilder sugli URL configurati con l'implementazione IServer .

Chiave: preferHostingUrls
Tipo: bool ( o true 1 )
Impostazione predefinita:true
Variabile di ambiente: <PREFIX_>_PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(false);

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 ( o true 1 )
Impostazione predefinita: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>();

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 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). 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 dispone di una propria API di configurazione dell'endpoint. Per altre informazioni, vedere KestrelImplementazione del 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.

Chiave: webroot
Tipo: string
Impostazione predefinita: il valore predefinito è wwwroot . Il percorso di {radice del contenuto}/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, vedere:

Gestire la durata dell'host

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

Esegui

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 o SIGTERM.

Avvio

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 è utile per ritardare l'avvio fino al segnale trasmesso 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 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));
        }
    }
}

Le app ASP.NET Core configurano e avviano un host. L'host è responsabile della gestione dell'avvio e della durata delle app.

Questo articolo illustra l'host generico di ASP.NET Core (HostBuilder), che si usa per le app che non elaborano le richieste HTTP.

Lo scopo dell'host generico è separare la pipeline HTTP dall'API dell'host Web, per abilitare una gamma più ampia di scenari host. 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.

L'host generico è una nuova funzionalità introdotta in ASP.NET Core 2.1 e non è adatto agli scenari di hosting Web. Per gli scenari di hosting Web usare l'host Web. L'host generico sostituirà l'host Web in una versione futura, funzionando come API host principale negli scenari sia HTTP che non HTTP.

Visualizzare o scaricare il codice di esempio (come scaricare)

Quando si esegue l'app di esempio in Visual Studio Code, usare un terminale esterno o integrato. Non eseguire l'esempio in un ambiente internalConsole.

Per impostare la console in Visual Studio Code:

  1. Aprire il file .vscode/launch.json.
  2. Nella configurazione .NET Core Launch (console) trovare la voce console. Impostare il valore su externalTerminal o integratedTerminal.

Introduzione

La libreria host generico è disponibile nello spazio dei nomi Microsoft.Extensions.Hosting e viene specificata dal pacchetto Microsoft.Extensions.Hosting. Il pacchetto Microsoft.Extensions.Hosting è incluso nel metapacchetto Microsoft.AspNetCore.App (ASP.NET Core 2.1 o versioni successive).

IHostedService è il punto di ingresso per l'esecuzione del codice. Ogni implementazione IHostedService viene eseguita nell'ordine di registrazione del servizio 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.

Configurare un host

IHostBuilder è il componente principale che le librerie e le app usano per inizializzare, compilare ed eseguire l'host:

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

    await host.RunAsync();
}

Opzioni

HostOptions configura le opzioni per IHost.

Timeout di arresto

ShutdownTimeout imposta il timeout per StopAsync. Il valore predefinito è cinque secondi.

La configurazione dell'opzione seguente in aumenta il timeout di arresto predefinito di Program.Main cinque secondi a 20 secondi:

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

Servizi predefiniti

I servizi seguenti vengono registrati durante l'inizializzazione dell'host:

Configurazione dell'host

La configurazione dell'host viene creata tramite:

Metodi di estensione

Chiave applicazione (nome)

La proprietà IHostingEnvironment.ApplicationName viene impostata dalla configurazione dell'host durante la costruzione dell'host. Per impostare il valore in modo esplicito, usare HostDefaults.ApplicationKey:

Chiave: applicationName
Tipo: string
Impostazione predefinita: il nome dell'assembly contenente il punto di ingresso dell'app.
Impostare usando: HostBuilderContext.HostingEnvironment.ApplicationName
Variabile di ambiente: <PREFIX_>APPLICATIONNAME ( è <PREFIX_> facoltativo e definito dall'utente)

Radice del contenuto

Questa impostazione determina la posizione da cui l'host inizia la ricerca dei file di contenuto.

Chiave: contentRoot
Tipo: string
Impostazione predefinita: il valore predefinito corrisponde alla cartella contenente l'assembly dell'app.
Impostare usando: UseContentRoot
Variabile di ambiente: <PREFIX_>CONTENTROOT ( è <PREFIX_> facoltativo e definito dall'utente)

Se il percorso non esiste, l'host non verrà avviato.

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

Per altre informazioni, vedere Nozioni fondamentali: radice del contenuto.

Ambiente

Imposta l'ambiente dell'app.

Chiave: environment
Tipo: string
Impostazione predefinita:Production
Impostare usando: UseEnvironment
Variabile di ambiente: <PREFIX_>ENVIRONMENT ( è <PREFIX_> facoltativo e definito dall'utente)

L'ambiente può essere impostato su qualsiasi valore. I valori definiti dal framework includono Development, Staging e Production. Per i valori non viene fatto distinzione tra maiuscole e minuscole.

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

ConfigureHostConfiguration

ConfigureHostConfiguration usa un'interfaccia IConfigurationBuilder per creare un'interfaccia IConfiguration per l'host. La configurazione dell'host viene usata per inizializzare l'interfaccia IHostingEnvironment da usare nel processo di compilazione dell'app.

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.

Nessun provider è incluso per impostazione predefinita. È necessario specificare in modo esplicito tutti i provider di configurazione richiesti dall'app in ConfigureHostConfiguration, inclusi:

  • Configurazione dei file (ad esempio, da un file hostsettings.json).
  • Configurazione delle variabili di ambiente.
  • Configurazione degli argomenti della riga di comando.
  • Tutti gli altri provider di configurazione necessari.

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. L'app di esempio usa un file JSON, hostsettings.json, e chiama AddJsonFile per utilizzare le impostazioni di configurazione host del file.

Per aggiungere la configurazione delle variabili di ambiente dell'host, chiamare AddEnvironmentVariables sul generatore di host. AddEnvironmentVariables accetta un prefisso facoltativo definito dall'utente. L'app di esempio usa un prefisso di PREFIX_. Il prefisso viene rimosso quando vengono lette le variabili di ambiente. 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.

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. Durante lo sviluppo in Visual Studio Code, le variabili di ambiente possono essere impostate nel file .vscode/launch.json. Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

La configurazione della riga di comando viene aggiunta chiamando 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.

hostsettings.json:

{
  "environment": "Development"
}

È possibile fornire una configurazione aggiuntiva con le chiavi applicationName e contentRoot.

Configurazione di esempio di HostBuilder che usa ConfigureHostConfiguration:

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

ConfigureAppConfiguration

La configurazione dell'app viene creata chiamando ConfigureAppConfiguration sull'implementazione IHostBuilder. ConfigureAppConfiguration usa un'interfaccia IConfigurationBuilder per creare un'interfaccia IConfiguration per l'app. 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 in Services.

La configurazione dell'app riceve automaticamente la configurazione dell'host fornita da ConfigureHostConfiguration.

Configurazione app di esempio che usa 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:

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

appsettings.Development.json:

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

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. L'app di esempio sposta i file delle impostazioni dell'app JSON e hostsettings.json con l'elemento <Content> seguente:

<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. 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. Per altre informazioni, vedere Configurazione in ASP.NET Core.

ConfigureServices

ConfigureServices aggiunge servizi al contenitore di inserimento delle dipendenze dell'app. ConfigureServices può essere chiamato più volte e i risultati si sommano.

Un servizio ospitato è una classe con logica di attività in background che implementa l'interfaccia IHostedService. Per altre informazioni, vedere 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):

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

ConfigureLogging

ConfigureLogging aggiunge un delegato per configurare l'interfaccia ILoggingBuilder fornita. ConfigureLogging può essere chiamato più volte e i risultati si sommano.

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

UseConsoleLifetime

UseConsoleLifetimeè in ascolto di CTRL + C/SIGINT o SIGTERM e chiama StopApplication per avviare il processo di arresto. UseConsoleLifetimesblocca estensioni come RunAsync e WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime è preregistrata come implementazione di durata predefinita. Viene usata l'ultima durata registrata.

var host = new HostBuilder()
    .UseConsoleLifetime()

Configurazione contenitore

Per supportare l'inserimento di altri contenitori, l'host può accettare un elemento 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. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) esegue l'override della factory predefinita usata per la creazione del provider di servizi dell'app.

La configurazione del contenitore personalizzato è gestita dal metodo ConfigureContainer. ConfigureContainer offre un'esperienza fortemente tipizzata per la configurazione del contenitore sulla base dell'API host sottostante. ConfigureContainer può essere chiamato più volte e i risultati si sommano.

Creare un contenitore di servizi per l'app:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Specificare una factory per il contenitore di servizi:

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:

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

Estendibilità

L'estensibilità host viene eseguita con i metodi di estensione su 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.

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:

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'host

L'implementazione IHost è responsabile dell'avvio e arresto delle implementazioni IHostedService che sono registrate nel contenitore di servizi.

Esegui

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

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

        host.Run();
    }
}

RunAsync

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

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

        await host.RunAsync();
    }
}

RunConsoleAsync

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

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

        await hostBuilder.RunConsoleAsync();
    }
}

Start e StopAsync

Start avvia l'host in modo sincrono.

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

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 StopAsync

StartAsync avvia l'app.

StopAsync arresta l'app.

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

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

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdownviene attivato tramite IHostLifetime , ad esempio Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (rimane in ascolto di CTRL + C/SIGINT o SIGTERM). WaitForShutdown chiama StopAsync.

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

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

WaitForShutdownAsync restituisce un elemento Task che viene completato quando viene attivato l'arresto tramite il token specificato, quindi chiama 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 esterno

Il controllo esterno 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));
        }
    }
}

WaitForStartAsync viene chiamato all'avvio di StartAsync, che attende il completamento prima di continuare. Questo è utile per ritardare l'avvio fino al segnale trasmesso da un evento esterno.

Interfaccia IHostingEnvironment

IHostingEnvironment include informazioni sull'ambiente di hosting dell'app. Usare l'inserimento di un costruttore per ottenere IHostingEnvironment per poterne usare le proprietà e i metodi di estensione:

public class MyClass
{
    private readonly IHostingEnvironment _env;

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

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

Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Interfaccia IApplicationLifetime

IApplicationLifetime consente attività post-avvio e di arresto, incluse le richieste di arresto normale. Tre proprietà nell'interfaccia sono token di annullamento usati per registrare i metodi Action che definiscono gli eventi di avvio e arresto.

Token di annullamento Attivato quando…
ApplicationStarted L'host è stato completamente avviato.
ApplicationStopped L'host sta completando un arresto normale. Tutte le richieste devono essere elaborate. L'arresto è bloccato fino al completamento di questo evento.
ApplicationStopping L'host sta eseguendo un arresto normale. È possibile che le richieste siano ancora in esecuzione. L'arresto è bloccato fino al completamento di questo evento.

Inserire tramite costruttore il servizio IApplicationLifetime in qualsiasi classe. L'app di esempio usa l'inserimento di costruttori in una classe LifetimeEventsHostedService (implementazione IHostedService) per registrare gli eventi.

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. La classe seguente usa StopApplication per arrestare normalmente un'app quando viene chiamato il metodo Shutdown della classe:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Risorse aggiuntive

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

    Nota

    I collegamenti alla documentazione ASP.NET Core origine di riferimento caricano il ramo del repository, che rappresenta lo sviluppo corrente dell'unità di prodotto per la versione successiva main di ASP.NET Core. Per selezionare il ramo per una versione diversa, usare l'elenco a discesa Cambia rami o tag per selezionare il ramo. Ad esempio, selezionare il release/5.0 ramo per la ASP.NET Core versione 5.0.