Host genérico do .NET no ASP.NET Core

  • Artigo
  • 38 minutos para o fim da leitura

Este artigo fornece informações sobre como usar o Host Genérico do .NET no ASP.NET Core.

Os modelos de ASP.NET Core criam um WebApplicationBuilder e WebApplication, que fornecem uma maneira simplificada de configurar e executar aplicativos Web sem uma Startup classe. Para obter mais informações sobre WebApplicationBuilder e WebApplication, consulte Migrar de ASP.NET Core 5.0 para 6.0.

Para obter informações sobre como usar o Host Genérico do .NET em aplicativos de console, consulte Host Genérico do .NET.

Definição do host

Um host é um objeto que encapsula os recursos de um aplicativo, tais como:

  • DI (injeção de dependência)
  • Log
  • Configuração
  • Implementações de IHostedService

Quando um host é iniciado, ele chama IHostedService.StartAsync em cada implementação de IHostedService registrada na coleção de serviços hospedados do contêiner de serviço. Em um aplicativo Web, uma das implementações de IHostedService é um serviço Web que inicia uma implementação do servidor HTTP.

Incluir todos os recursos interdependentes do aplicativo em um objeto permite o controle sobre a inicialização do aplicativo e o desligamento normal.

Configurar um host

O host normalmente é configurado, compilado e executado por código no Program.cs. O código a seguir cria um host com uma implementação IHostedService adicionada ao contêiner de DI:

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

Para uma carga de trabalho HTTP, chame ConfigureWebHostDefaults após CreateDefaultBuilder:

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

Configurações do construtor padrão

O método CreateDefaultBuilder:

  • Define a raiz do conteúdo como o caminho retornado por GetCurrentDirectory.
  • Carrega a configuração do host de:
    • Variáveis de ambiente prefixadas com DOTNET_.
    • Argumentos de linha de comando.
  • Carrega a configuração do aplicativo de:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Segredos do usuário quando o aplicativo é executado no ambiente Development.
    • Variáveis de ambiente.
    • Argumentos de linha de comando.
  • Adiciona os seguintes provedores de log :
    • Console
    • Depurar
    • EventSource
    • EventLog (somente quando em execução no Windows)
  • Habilita a validação de escopo e a validação de dependência quando o ambiente é o de Desenvolvimento.

O método ConfigureWebHostDefaults:

As seções Configurações para todos os tipos de aplicativo e Configurações para aplicativos Web neste artigo mostram como substituir as configurações do construtor padrão.

Serviços fornecidos pela estrutura

Os seguintes serviços são registrados automaticamente:

Para obter mais informações sobre serviços fornecidos pela estrutura, consulte Injeção de dependência em ASP.NET Core.

IHostApplicationLifetime

Injete o serviço IHostApplicationLifetime (anteriormente conhecido como IApplicationLifetime) em qualquer classe para lidar com tarefas de pós-inicialização e de desligamento normal. Três propriedades na interface são tokens de cancelamento usados para registrar métodos de manipulador de eventos de inicialização e desligamento do aplicativo. A interface também inclui um StopApplication método , que permite que os aplicativos solicitem um desligamento normal.

Ao executar um desligamento normal, o host:

  • Dispara os ApplicationStopping manipuladores de eventos, o que permite que o aplicativo execute a lógica antes do início do processo de desligamento.
  • Interrompe o servidor, que desabilita novas conexões. O servidor aguarda a conclusão das solicitações em conexões existentes, desde que o tempo limite de desligamento permita. O servidor envia o cabeçalho de fechamento de conexão para solicitações adicionais em conexões existentes.
  • Dispara os ApplicationStopped manipuladores de eventos, o que permite que o aplicativo execute a lógica após o desligamento do aplicativo.

O exemplo a seguir é uma implementação IHostedService que registra manipuladores IHostApplicationLifetime de eventos:

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

A implementação IHostLifetime controla quando o host é iniciado e quando ele é interrompido. A última implementação registrada é usada.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime é a implementação IHostLifetime padrão. ConsoleLifetime:

IHostEnvironment

Injete o serviço IHostEnvironment em uma classe para obter informações sobre as seguintes configurações:

Os aplicativos Web implementam a IWebHostEnvironment interface , que herda IHostEnvironment e adiciona o WebRootPath.

Configuração do host

A configuração do host é usada para as propriedades da implementação IHostEnvironment.

A configuração do host está disponível de dentro ConfigureAppConfigurationdo HostBuilderContext.Configuration . Após ConfigureAppConfiguration, HostBuilderContext.Configuration é substituído com a configuração do aplicativo.

Para adicionar a configuração do host, chame ConfigureHostConfiguration em IHostBuilder. ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos. O host usa a opção que define um valor por último em uma chave determinada.

O provedor de variável de ambiente com argumentos de prefixo DOTNET_ e linha de comando são incluídos pelo CreateDefaultBuilder. Para aplicativos Web, o provedor de variáveis de ambiente com o prefixo ASPNETCORE_ é adicionado. O prefixo é removido quando as variáveis de ambiente são lidas. Por exemplo, o valor da variável de ambiente de ASPNETCORE_ENVIRONMENT torna-se o valor de configuração de host para a chave environment.

O exemplo a seguir cria a configuração de host:

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

Configuração do aplicativo

A configuração de aplicativo é criada chamando ConfigureAppConfiguration em IHostBuilder. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos. O aplicativo usa a opção que define um valor por último em uma chave determinada.

A configuração criada por ConfigureAppConfiguration está disponível em HostBuilderContext.Configuration para operações subsequentes e como um serviço da DI. A configuração do host também é adicionada à configuração do aplicativo.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Configurações para todos os tipos de aplicativo

Esta seção lista as configurações de host que se aplicam a cargas de trabalho HTTP e àquelas não HTTP. Por padrão, as variáveis de ambiente usadas para definir essas configurações podem ter um DOTNET_ prefixo ou ASPNETCORE_ , que aparece na lista de configurações a seguir como o {PREFIX_} espaço reservado. Para obter mais informações, consulte a seção Configurações do construtor padrão e Configuração: variáveis de ambiente.

ApplicationName

A IHostEnvironment.ApplicationName propriedade é definida a partir da configuração do host durante a construção do host.

Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Variável de ambiente: {PREFIX_}APPLICATIONNAME

Para definir esse valor, use a variável de ambiente.

ContentRoot

A IHostEnvironment.ContentRootPath propriedade determina onde o host começa a pesquisar arquivos de conteúdo. Se o caminho não existir, o host não será iniciado.

Chave: contentRoot
Tipo: string
Padrão: a pasta na qual o assembly do aplicativo reside.
Variável de ambiente: {PREFIX_}CONTENTROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseContentRoot em IHostBuilder:

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

Para obter mais informações, consulte:

EnvironmentName

A IHostEnvironment.EnvironmentName propriedade pode ser definida como qualquer valor. Os valores definidos pela estrutura incluem Development, Staging e Production. Os valores não diferenciam maiúsculas de minúsculas.

Chave: environment
Tipo: string
Padrão: Production
Variável de ambiente: {PREFIX_}ENVIRONMENT

Para definir esse valor, use a variável de ambiente ou a chamada UseEnvironment em IHostBuilder:

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

ShutdownTimeout

O HostOptions.ShutdownTimeout define o tempo limite para StopAsync. O valor padrão é cinco segundos. Durante o período de tempo limite, o host:

Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos restantes serão parados quando o aplicativo for desligado. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5 segundos
Variável de ambiente: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Para definir esse valor, use a variável de ambiente ou configure HostOptions. O exemplo a seguir define o tempo limite para 20 segundos:

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

Desabilitar o recarregamento da configuração do aplicativo na alteração

Por padrão, appsettings.json e appsettings.{Environment}.json são recarregados quando o arquivo é alterado. Para desabilitar esse comportamento de recarregamento no ASP.NET Core 5.0 ou posterior, defina a hostBuilder:reloadConfigOnChange chave como false.

Chave: hostBuilder:reloadConfigOnChange
Tipo: bool (true ou false)
Padrão: true
Argumento de linha de comando: hostBuilder:reloadConfigOnChange
Variável de ambiente: {PREFIX_}hostBuilder:reloadConfigOnChange

Aviso

O separador de dois-pontos (:) não funciona com chaves hierárquicas de variável de ambiente em todas as plataformas. Para obter mais informações, confira Variáveis de ambiente.

Configurações para aplicativos Web

Algumas configurações de host se aplicam somente a cargas de trabalho HTTP. Por padrão, as variáveis de ambiente usadas para definir essas configurações podem ter um DOTNET_ prefixo ou ASPNETCORE_ , que aparece na lista de configurações a seguir como o {PREFIX_} espaço reservado.

Métodos de extensão em IWebHostBuilder estão disponíveis para essas configurações. Exemplos de código que mostram como chamar os métodos de extensão pressupõem que webBuilder é uma instância de IWebHostBuilder, conforme mostrado no exemplo a seguir:

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

CaptureStartupErrors

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

Chave: captureStartupErrors
Tipo: bool (true/1 ou false/0)
Padrão: o padrão é a false menos que o aplicativo seja executado com Kestrel o IIS por trás, onde o padrão é true.
Variável de ambiente: {PREFIX_}CAPTURESTARTUPERRORS

Para definir esse valor, use a configuração ou a chamada CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Quando habilitado (ou quando o ambiente é Development), o aplicativo captura erros detalhados.

Chave: detailedErrors
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}DETAILEDERRORS

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização. Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de hospedagem sempre incluem o assembly do aplicativo. Quando assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar seus serviços comuns durante a inicialização.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupExcludeAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

Chave: hostingStartupExcludeAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HTTPS_Port

A porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: string
Padrão: um valor padrão não é definido.
Variável de ambiente: {PREFIX_}HTTPS_PORT

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

PreferHostingUrls

Indica se o host deve escutar nas URLs configuradas com o IWebHostBuilder em vez dessas URLs configuradas com a IServer implementação.

Chave: preferHostingUrls
Tipo: bool (true/1 ou false/0)
Padrão: true
Variável de ambiente: {PREFIX_}PREFERHOSTINGURLS

Para definir esse valor, use a variável de ambiente ou a chamada PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, confira Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartup
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}PREVENTHOSTINGSTARTUP

Para definir esse valor, use a variável de ambiente ou a chamada UseSetting:

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

StartupAssembly

O assembly no qual pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Variável de ambiente: {PREFIX_}STARTUPASSEMBLY

Para definir esse valor, use a variável de ambiente ou a chamada UseStartup. UseStartup pode usar um nome de assembly (string) ou um tipo (TStartup). Se vários métodos UseStartup forem chamados, o último terá precedência.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Quando habilitado, suprime a hospedagem de mensagens de status de inicialização.

Chave: suppressStatusMessages
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}SUPPRESSSTATUSMESSAGES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

URLs

Uma lista delimitada por ponto-e-vírgula de endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações. Por exemplo, http://localhost:123. Use "*" para indicar que o servidor deve escutar solicitações em qualquer endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL. Os formatos compatíveis variam dependendo dos servidores.

Chave: urls
Tipo: string
Padrão: http://localhost:5000 e https://localhost:5001
Variável de ambiente: {PREFIX_}URLS

Para definir esse valor, use a variável de ambiente ou a chamada UseUrls:

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

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Configurar pontos de extremidade para o servidor Web ASP.NET CoreKestrel.

WebRoot

A propriedade IWebHostEnvironment.WebRootPath determina o caminho relativo para os ativos estáticos do aplicativo. Se o caminho não existir, um provedor de arquivo não operacional será usado.

Chave: webroot
Tipo: string
Padrão: o padrão é wwwroot. O caminho para {raiz de conteúdo}/wwwroot deve existir.
Variável de ambiente: {PREFIX_}WEBROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseWebRoot em IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para obter mais informações, consulte:

Gerenciar o tempo de vida do host

Chame métodos na implementação de IHost criada para iniciar e parar o aplicativo. Esses métodos afetam todas as IHostedService implementações registradas no contêiner de serviço.

Executar

Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado.

RunAsync

RunAsync executa o aplicativo e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

RunConsoleAsync

RunConsoleAsync habilita o suporte ao console, cria e inicia o host e aguarda ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM para desligar.

Iniciar

Start inicia o host de forma síncrona.

StartAsync

StartAsync inicia o host e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído antes de continuar. Esse método pode ser usado para atrasar a inicialização até ser sinalizado por um evento externo.

StopAsync

StopAsync tenta parar o host dentro do tempo limite fornecido.

WaitForShutdown

WaitForShutdown bloqueia o thread de chamada até que o desligamento seja disparado pelo IHostLifetime, como por meio de Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do token fornecido e chama StopAsync.

Os modelos de ASP.NET Core criam um host genérico do .NET Core (HostBuilder).

Este artigo fornece informações sobre como usar o Host Genérico do .NET no ASP.NET Core. Para obter informações sobre como usar o Host Genérico do .NET em aplicativos de console, consulte Host Genérico do .NET.

Definição de host

Um host é um objeto que encapsula os recursos de um aplicativo, tais como:

  • DI (injeção de dependência)
  • Log
  • Configuração
  • Implementações de IHostedService

Quando um host é iniciado, ele chama IHostedService.StartAsync em cada implementação de IHostedService registrada na coleção de serviços hospedados do contêiner de serviço. Em um aplicativo Web, uma das implementações de IHostedService é um serviço Web que inicia uma implementação do servidor HTTP.

O principal motivo para incluir todos os recursos interdependentes do aplicativo em um objeto é o gerenciamento de tempo de vida: controle sobre a inicialização do aplicativo e desligamento normal.

Configurar um host

O host normalmente é configurado, compilado e executado pelo código na classe Program. O método Main:

  • Chama um método CreateHostBuilder para criar e configurar um objeto construtor.
  • Chama os métodos Build e Run no objeto construtor.

Os modelos da Web ASP.NET Core geram o seguinte código para criar um 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>();
            });
}

O código a seguir cria uma carga de trabalho não HTTP com uma implementação IHostedService adicionada ao contêiner de 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>();
            });
}

Para uma carga de trabalho HTTP, o método Main é o mesmo, mas CreateHostBuilder chama ConfigureWebHostDefaults:

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

Se o aplicativo usar o Entity Framework Core, não altere o nome ou a assinatura do método CreateHostBuilder. As ferramentas do Entity Framework Core esperam encontrar um método CreateHostBuilder que elas possam chamar em tempo de design para configurar o host sem executar o aplicativo. Para obter mais informações, confira Criação de DbContext no tempo de design.

Configurações do construtor padrão

O método CreateDefaultBuilder:

  • Define a raiz do conteúdo como o caminho retornado por GetCurrentDirectory.
  • Carrega a configuração do host de:
    • Variáveis de ambiente prefixadas com DOTNET_.
    • Argumentos de linha de comando.
  • Carrega a configuração do aplicativo de:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Segredos do usuário quando o aplicativo é executado no ambiente Development.
    • Variáveis de ambiente.
    • Argumentos de linha de comando.
  • Adiciona os seguintes provedores de log :
    • Console
    • Depurar
    • EventSource
    • EventLog (somente quando em execução no Windows)
  • Habilita a validação de escopo e a validação de dependência quando o ambiente é o de Desenvolvimento.

O método ConfigureWebHostDefaults:

As seções Configurações para todos os tipos de aplicativo e Configurações para aplicativos Web neste artigo mostram como substituir as configurações do construtor padrão.

Serviços fornecidos pela estrutura

Os seguintes serviços são registrados automaticamente:

Para obter mais informações sobre serviços fornecidos pela estrutura, consulte Injeção de dependência em ASP.NET Core.

IHostApplicationLifetime

Injete o serviço IHostApplicationLifetime (anteriormente conhecido como IApplicationLifetime) em qualquer classe para lidar com tarefas de pós-inicialização e de desligamento normal. Três propriedades na interface são tokens de cancelamento usados para registrar métodos de manipulador de eventos de inicialização e desligamento do aplicativo. A interface também inclui um método StopApplication.

O exemplo a seguir é uma implementação IHostedService que registra eventos 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

A implementação IHostLifetime controla quando o host é iniciado e quando ele é interrompido. A última implementação registrada é usada.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime é a implementação IHostLifetime padrão. ConsoleLifetime:

IHostEnvironment

Injete o serviço IHostEnvironment em uma classe para obter informações sobre as seguintes configurações:

Os aplicativos Web implementam a IWebHostEnvironment interface , que herda IHostEnvironment e adiciona o WebRootPath.

Configuração do host

A configuração do host é usada para as propriedades da implementação IHostEnvironment.

A configuração do host está disponível de dentro ConfigureAppConfigurationdo HostBuilderContext.Configuration . Após ConfigureAppConfiguration, HostBuilderContext.Configuration é substituído com a configuração do aplicativo.

Para adicionar a configuração do host, chame ConfigureHostConfiguration em IHostBuilder. ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos. O host usa a opção que define um valor por último em uma chave determinada.

O provedor de variável de ambiente com argumentos de prefixo DOTNET_ e linha de comando são incluídos pelo CreateDefaultBuilder. Para aplicativos Web, o provedor de variáveis de ambiente com o prefixo ASPNETCORE_ é adicionado. O prefixo é removido quando as variáveis de ambiente são lidas. Por exemplo, o valor da variável de ambiente de ASPNETCORE_ENVIRONMENT torna-se o valor de configuração de host para a chave environment.

O exemplo a seguir cria a configuração de 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);
    });

Configuração do aplicativo

A configuração de aplicativo é criada chamando ConfigureAppConfiguration em IHostBuilder. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos. O aplicativo usa a opção que define um valor por último em uma chave determinada.

A configuração criada por ConfigureAppConfiguration está disponível em HostBuilderContext.Configuration para operações subsequentes e como um serviço da DI. A configuração do host também é adicionada à configuração do aplicativo.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Configurações para todos os tipos de aplicativo

Esta seção lista as configurações de host que se aplicam a cargas de trabalho HTTP e àquelas não HTTP. Por padrão, as variáveis de ambiente usadas para definir essas configurações podem ter um DOTNET_ prefixo ou ASPNETCORE_ , que aparece na lista de configurações a seguir como o {PREFIX_} espaço reservado. Para obter mais informações, consulte a seção Configurações do construtor padrão e Configuração: variáveis de ambiente.

ApplicationName

A IHostEnvironment.ApplicationName propriedade é definida a partir da configuração do host durante a construção do host.

Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Variável de ambiente: {PREFIX_}APPLICATIONNAME

Para definir esse valor, use a variável de ambiente.

ContentRoot

A IHostEnvironment.ContentRootPath propriedade determina onde o host começa a pesquisar arquivos de conteúdo. Se o caminho não existir, o host não será iniciado.

Chave: contentRoot
Tipo: string
Padrão: a pasta em que o assembly do aplicativo reside.
Variável de ambiente: {PREFIX_}CONTENTROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseContentRoot em IHostBuilder:

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

Para obter mais informações, consulte:

EnvironmentName

A IHostEnvironment.EnvironmentName propriedade pode ser definida como qualquer valor. Os valores definidos pela estrutura incluem Development, Staging e Production. Os valores não diferenciam maiúsculas de minúsculas.

Chave: environment
Tipo: string
Padrão: Production
Variável de ambiente: {PREFIX_}ENVIRONMENT

Para definir esse valor, use a variável de ambiente ou a chamada UseEnvironment em IHostBuilder:

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

ShutdownTimeout

O HostOptions.ShutdownTimeout define o tempo limite para StopAsync. O valor padrão é cinco segundos. Durante o período de tempo limite, o host:

Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos restantes serão parados quando o aplicativo for desligado. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5 segundos
Variável de ambiente: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Para definir esse valor, use a variável de ambiente ou configure HostOptions. O exemplo a seguir define o tempo limite para 20 segundos:

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

Desabilitar o recarregamento da configuração do aplicativo na alteração

Por padrão, appsettings.json e appsettings.{Environment}.json são recarregados quando o arquivo é alterado. Para desabilitar esse comportamento de recarregamento no ASP.NET Core 5.0 ou posterior, defina a hostBuilder:reloadConfigOnChange chave como false.

Chave: hostBuilder:reloadConfigOnChange
Tipo: bool (true ou false)
Padrão: true
Argumento de linha de comando: hostBuilder:reloadConfigOnChange
Variável de ambiente: {PREFIX_}hostBuilder:reloadConfigOnChange

Aviso

O separador de dois-pontos (:) não funciona com chaves hierárquicas de variável de ambiente em todas as plataformas. Para obter mais informações, confira Variáveis de ambiente.

Configurações para aplicativos Web

Algumas configurações de host se aplicam somente a cargas de trabalho HTTP. Por padrão, as variáveis de ambiente usadas para definir essas configurações podem ter um DOTNET_ prefixo ou ASPNETCORE_ , que aparece na lista de configurações a seguir como o {PREFIX_} espaço reservado.

Métodos de extensão em IWebHostBuilder estão disponíveis para essas configurações. Exemplos de código que mostram como chamar os métodos de extensão pressupõem que webBuilder é uma instância de IWebHostBuilder, conforme mostrado no exemplo a seguir:

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

CaptureStartupErrors

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

Chave: captureStartupErrors
Tipo: bool (true/1 ou false/0)
Padrão: o padrão é a false menos que o aplicativo seja executado com Kestrel o IIS por trás, onde o padrão é true.
Variável de ambiente: {PREFIX_}CAPTURESTARTUPERRORS

Para definir esse valor, use a configuração ou a chamada CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Quando habilitado (ou quando o ambiente é Development), o aplicativo captura erros detalhados.

Chave: detailedErrors
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}DETAILEDERRORS

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização. Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de hospedagem sempre incluem o assembly do aplicativo. Quando assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar seus serviços comuns durante a inicialização.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupExcludeAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

Chave: hostingStartupExcludeAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HTTPS_Port

A porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: string
Padrão: um valor padrão não é definido.
Variável de ambiente: {PREFIX_}HTTPS_PORT

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

PreferHostingUrls

Indica se o host deve escutar nas URLs configuradas com o IWebHostBuilder em vez dessas URLs configuradas com a IServer implementação.

Chave: preferHostingUrls
Tipo: bool (true/1 ou false/0)
Padrão: true
Variável de ambiente: {PREFIX_}PREFERHOSTINGURLS

Para definir esse valor, use a variável de ambiente ou a chamada PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, confira Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartup
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}PREVENTHOSTINGSTARTUP

Para definir esse valor, use a variável de ambiente ou a chamada UseSetting:

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

StartupAssembly

O assembly no qual pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Variável de ambiente: {PREFIX_}STARTUPASSEMBLY

Para definir esse valor, use a variável de ambiente ou a chamada UseStartup. UseStartup pode usar um nome de assembly (string) ou um tipo (TStartup). Se vários métodos UseStartup forem chamados, o último terá precedência.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Quando habilitado, suprime a hospedagem de mensagens de status de inicialização.

Chave: suppressStatusMessages
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}SUPPRESSSTATUSMESSAGES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

URLs

Uma lista delimitada por ponto-e-vírgula de endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações. Por exemplo, http://localhost:123. Use "*" para indicar que o servidor deve escutar solicitações em qualquer endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL. Os formatos compatíveis variam dependendo dos servidores.

Chave: urls
Tipo: string
Padrão: http://localhost:5000 e https://localhost:5001
Variável de ambiente: {PREFIX_}URLS

Para definir esse valor, use a variável de ambiente ou a chamada UseUrls:

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

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Configurar pontos de extremidade para o servidor Web ASP.NET CoreKestrel.

WebRoot

A propriedade IWebHostEnvironment.WebRootPath determina o caminho relativo para os ativos estáticos do aplicativo. Se o caminho não existir, um provedor de arquivo não operacional será usado.

Chave: webroot
Tipo: string
Padrão: o padrão é wwwroot. O caminho para {content root}/wwwroot deve existir.
Variável de ambiente: {PREFIX_}WEBROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseWebRoot em IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para obter mais informações, consulte:

Gerenciar o tempo de vida do host

Chame métodos na implementação de IHost criada para iniciar e parar o aplicativo. Esses métodos afetam todas as IHostedService implementações registradas no contêiner de serviço.

Executar

Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado.

RunAsync

RunAsync executa o aplicativo e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

RunConsoleAsync

RunConsoleAsync habilita o suporte ao console, compila e inicia o host e aguarda o desligamento de Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM.

Iniciar

Start inicia o host de forma síncrona.

StartAsync

StartAsync inicia o host e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído antes de continuar. Esse método pode ser usado para atrasar a inicialização até ser sinalizado por um evento externo.

StopAsync

StopAsync tenta parar o host dentro do tempo limite fornecido.

WaitForShutdown

WaitForShutdown bloqueia o thread de chamada até que o desligamento seja disparado pelo IHostLifetime, como por meio de Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do token fornecido e chama StopAsync.

Controle externo

O controle direto do tempo de vida do host pode ser obtido usando os métodos que podem ser chamados externamente:

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

Os modelos de ASP.NET Core criam um Host Genérico do .NET Core (HostBuilder).

Este artigo fornece informações sobre como usar o Host Genérico do .NET no ASP.NET Core. Para obter informações sobre como usar o Host Genérico do .NET em aplicativos de console, consulte Host Genérico do .NET.

Definição do host

Um host é um objeto que encapsula os recursos de um aplicativo, tais como:

  • DI (injeção de dependência)
  • Log
  • Configuração
  • Implementações de IHostedService

Quando um host é iniciado, ele chama IHostedService.StartAsync em cada implementação de IHostedService registrada na coleção de serviços hospedados do contêiner de serviço. Em um aplicativo Web, uma das implementações de IHostedService é um serviço Web que inicia uma implementação do servidor HTTP.

O principal motivo para incluir todos os recursos interdependentes do aplicativo em um objeto é o gerenciamento de tempo de vida: controle sobre a inicialização do aplicativo e desligamento normal.

Configurar um host

O host normalmente é configurado, compilado e executado pelo código na classe Program. O método Main:

  • Chama um método CreateHostBuilder para criar e configurar um objeto construtor.
  • Chama os métodos Build e Run no objeto construtor.

Os modelos da Web ASP.NET Core geram o seguinte código para criar um Host Genérico:

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

O código a seguir cria um Host Genérico usando carga de trabalho não HTTP. A IHostedService implementação é adicionada ao contêiner de 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>();
            });
}

Para uma carga de trabalho HTTP, o método Main é o mesmo, mas CreateHostBuilder chama ConfigureWebHostDefaults:

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

O código anterior é gerado pelos modelos de ASP.NET Core.

Se o aplicativo usar o Entity Framework Core, não altere o nome ou a assinatura do método CreateHostBuilder. As ferramentas do Entity Framework Core esperam encontrar um método CreateHostBuilder que elas possam chamar em tempo de design para configurar o host sem executar o aplicativo. Para obter mais informações, confira Criação de DbContext no tempo de design.

Configurações do construtor padrão

O método CreateDefaultBuilder:

  • Define a raiz do conteúdo como o caminho retornado por GetCurrentDirectory.
  • Carrega a configuração do host de:
    • Variáveis de ambiente prefixadas com DOTNET_.
    • Argumentos de linha de comando.
  • Carrega a configuração do aplicativo de:
    • appsettings.json.
    • appsettings.{Environment}.json.
    • Segredos do usuário quando o aplicativo é executado no ambiente Development.
    • Variáveis de ambiente.
    • Argumentos de linha de comando.
  • Adiciona os seguintes provedores de log :
    • Console
    • Depurar
    • EventSource
    • EventLog (somente quando em execução no Windows)
  • Habilita a validação de escopo e a validação de dependência quando o ambiente é o de Desenvolvimento.

O método ConfigureWebHostDefaults:

As seções Configurações para todos os tipos de aplicativo e Configurações para aplicativos Web neste artigo mostram como substituir as configurações do construtor padrão.

Serviços fornecidos pela estrutura

Os seguintes serviços são registrados automaticamente:

Para obter mais informações sobre serviços fornecidos pela estrutura, consulte Injeção de dependência em ASP.NET Core.

IHostApplicationLifetime

Injete o serviço IHostApplicationLifetime (anteriormente conhecido como IApplicationLifetime) em qualquer classe para lidar com tarefas de pós-inicialização e de desligamento normal. Três propriedades na interface são tokens de cancelamento usados para registrar métodos de manipulador de eventos de inicialização e desligamento do aplicativo. A interface também inclui um método StopApplication.

O exemplo a seguir é uma implementação IHostedService que registra eventos 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

A implementação IHostLifetime controla quando o host é iniciado e quando ele é interrompido. A última implementação registrada é usada.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime é a implementação IHostLifetime padrão. ConsoleLifetime:

IHostEnvironment

Injete o serviço IHostEnvironment em uma classe para obter informações sobre as seguintes configurações:

Os aplicativos Web implementam a IWebHostEnvironment interface , que herda IHostEnvironment e adiciona o WebRootPath.

Configuração do host

A configuração do host é usada para as propriedades da implementação IHostEnvironment.

A configuração do host está disponível de dentro ConfigureAppConfigurationdo HostBuilderContext.Configuration . Após ConfigureAppConfiguration, HostBuilderContext.Configuration é substituído com a configuração do aplicativo.

Para adicionar a configuração do host, chame ConfigureHostConfiguration em IHostBuilder. ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos. O host usa a opção que define um valor por último em uma chave determinada.

O provedor de variável de ambiente com argumentos de prefixo DOTNET_ e linha de comando são incluídos pelo CreateDefaultBuilder. Para aplicativos Web, o provedor de variáveis de ambiente com o prefixo ASPNETCORE_ é adicionado. O prefixo é removido quando as variáveis de ambiente são lidas. Por exemplo, o valor da variável de ambiente de ASPNETCORE_ENVIRONMENT torna-se o valor de configuração de host para a chave environment.

O exemplo a seguir cria a configuração de 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);
    });

Configuração do aplicativo

A configuração de aplicativo é criada chamando ConfigureAppConfiguration em IHostBuilder. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos. O aplicativo usa a opção que define um valor por último em uma chave determinada.

A configuração criada por ConfigureAppConfiguration está disponível em HostBuilderContext.Configuration para operações subsequentes e como um serviço da DI. A configuração do host também é adicionada à configuração do aplicativo.

Para obter mais informações, consulte Configuração no ASP.NET Core.

Configurações para todos os tipos de aplicativo

Esta seção lista as configurações de host que se aplicam a cargas de trabalho HTTP e àquelas não HTTP. Por padrão, as variáveis de ambiente usadas para definir essas configurações podem ter um DOTNET_ prefixo ou ASPNETCORE_ , que aparece na configuração a seguir para o {PREFIX_} espaço reservado.

ApplicationName

A IHostEnvironment.ApplicationName propriedade é definida a partir da configuração do host durante a construção do host.

Chave: applicationName
Tipo: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.
Variável de ambiente: {PREFIX_}APPLICATIONNAME

Para definir esse valor, use a variável de ambiente.

ContentRoot

A IHostEnvironment.ContentRootPath propriedade determina onde o host começa a pesquisar arquivos de conteúdo. Se o caminho não existir, o host não será iniciado.

Chave: contentRoot
Tipo: string
Padrão: a pasta em que o assembly do aplicativo reside.
Variável de ambiente: {PREFIX_}CONTENTROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseContentRoot em IHostBuilder:

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

Para obter mais informações, consulte:

EnvironmentName

A IHostEnvironment.EnvironmentName propriedade pode ser definida como qualquer valor. Os valores definidos pela estrutura incluem Development, Staging e Production. Os valores não diferenciam maiúsculas de minúsculas.

Chave: environment
Tipo: string
Padrão: Production
Variável de ambiente: {PREFIX_}ENVIRONMENT

Para definir esse valor, use a variável de ambiente ou a chamada UseEnvironment em IHostBuilder:

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

ShutdownTimeout

O HostOptions.ShutdownTimeout define o tempo limite para StopAsync. O valor padrão é cinco segundos. Durante o período de tempo limite, o host:

Se o período de tempo limite expirar antes que todos os serviços hospedados parem, os serviços ativos restantes serão parados quando o aplicativo for desligado. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

Chave: shutdownTimeoutSeconds
Tipo: int
Padrão: 5 segundos
Variável de ambiente: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

Para definir esse valor, use a variável de ambiente ou configure HostOptions. O exemplo a seguir define o tempo limite para 20 segundos:

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

Configurações para aplicativos Web

Algumas configurações de host se aplicam somente a cargas de trabalho HTTP. Por padrão, variáveis de ambiente usadas para definir essas configurações podem ter um prefixo DOTNET_ ou ASPNETCORE_.

Métodos de extensão em IWebHostBuilder estão disponíveis para essas configurações. Exemplos de código que mostram como chamar os métodos de extensão pressupõem que webBuilder é uma instância de IWebHostBuilder, conforme mostrado no exemplo a seguir:

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

CaptureStartupErrors

Quando false, erros durante a inicialização resultam no encerramento do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

Chave: captureStartupErrors
Tipo: bool (true/1 ou false/0)
Padrão: o padrão é , false a menos que o aplicativo seja executado com Kestrel por trás do IIS, em que o padrão é true.
Variável de ambiente: {PREFIX_}CAPTURESTARTUPERRORS

Para definir esse valor, use a configuração ou a chamada CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Quando habilitado (ou quando o ambiente é Development), o aplicativo captura erros detalhados.

Chave: detailedErrors
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}DETAILEDERRORS

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização. Embora o valor padrão da configuração seja uma cadeia de caracteres vazia, os assemblies de inicialização de hospedagem sempre incluem o assembly do aplicativo. Quando assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para carregamento quando o aplicativo compilar seus serviços comuns durante a inicialização.

Chave: hostingStartupAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HostingStartupExcludeAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.

Chave: hostingStartupExcludeAssemblies
Tipo: string
Padrão: cadeia de caracteres vazia
Variável de ambiente: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

HTTPS_Port

A porta de redirecionamento HTTPS. Uso em aplicação de HTTPS.

Chave: https_port
Tipo: string
Padrão: um valor padrão não é definido.
Variável de ambiente: {PREFIX_}HTTPS_PORT

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

PreferHostingUrls

Indica se o host deve escutar nas URLs configuradas com o IWebHostBuilder em vez dessas URLs configuradas com a IServer implementação.

Chave: preferHostingUrls
Tipo: bool (true/1 ou false/0)
Padrão: true
Variável de ambiente: {PREFIX_}PREFERHOSTINGURLS

Para definir esse valor, use a variável de ambiente ou a chamada PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo. Para obter mais informações, confira Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartup
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}PREVENTHOSTINGSTARTUP

Para definir esse valor, use a variável de ambiente ou a chamada UseSetting:

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

StartupAssembly

O assembly no qual pesquisar pela classe Startup.

Chave: startupAssembly
Tipo: string
Padrão: o assembly do aplicativo
Variável de ambiente: {PREFIX_}STARTUPASSEMBLY

Para definir esse valor, use a variável de ambiente ou a chamada UseStartup. UseStartup pode usar um nome de assembly (string) ou um tipo (TStartup). Se vários métodos UseStartup forem chamados, o último terá precedência.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

SuppressStatusMessages

Quando habilitado, suprime a hospedagem de mensagens de status de inicialização.

Chave: suppressStatusMessages
Tipo: bool (true/1 ou false/0)
Padrão: false
Variável de ambiente: {PREFIX_}SUPPRESSSTATUSMESSAGES

Para definir esse valor, use a configuração ou a chamada UseSetting:

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

URLs

Uma lista delimitada por ponto-e-vírgula de endereços IP ou endereços de host com portas e protocolos que o servidor deve escutar para solicitações. Por exemplo, http://localhost:123. Use "*" para indicar que o servidor deve escutar solicitações em qualquer endereço IP ou nome do host usando a porta e o protocolo especificados (por exemplo, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL. Os formatos compatíveis variam dependendo dos servidores.

Chave: urls
Tipo: string
Padrão: http://localhost:5000 e https://localhost:5001
Variável de ambiente: {PREFIX_}URLS

Para definir esse valor, use a variável de ambiente ou a chamada UseUrls:

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

Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, consulte Kestrel Implementação de servidor Web em ASP.NET Core.

WebRoot

A propriedade IWebHostEnvironment.WebRootPath determina o caminho relativo para os ativos estáticos do aplicativo. Se o caminho não existir, um provedor de arquivo não operacional será usado.

Chave: webroot
Tipo: string
Padrão: o padrão é wwwroot. O caminho para {raiz de conteúdo}/wwwroot deve existir.
Variável de ambiente: {PREFIX_}WEBROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseWebRoot em IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para obter mais informações, consulte:

Gerenciar o tempo de vida do host

Chame métodos na implementação de IHost criada para iniciar e parar o aplicativo. Esses métodos afetam todas as IHostedService implementações registradas no contêiner de serviço.

Executar

Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado.

RunAsync

RunAsync executa o aplicativo e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

RunConsoleAsync

RunConsoleAsync habilita o suporte ao console, cria e inicia o host e aguarda ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM para desligar.

Iniciar

Start inicia o host de forma síncrona.

StartAsync

StartAsync inicia o host e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.

WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído antes de continuar. Esse método pode ser usado para atrasar a inicialização até ser sinalizado por um evento externo.

StopAsync

StopAsync tenta parar o host dentro do tempo limite fornecido.

WaitForShutdown

WaitForShutdown bloqueia o thread de chamada até que o desligamento seja disparado pelo IHostLifetime, como por meio de Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do token fornecido e chama StopAsync.

Controle externo

O controle direto do tempo de vida do host pode ser obtido usando os métodos que podem ser chamados externamente:

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

Recursos adicionais