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

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 classe Startup. Para obter mais informações sobre WebApplicationBuilder e WebApplication, confira Migrar do 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, confira 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.

A inclusão de todos os recursos interdependentes do aplicativo em um objeto habilita o controle sobre a inicialização do aplicativo e desligamento normal.

Configurar um host

O host normalmente é configurado, compilado e executado pelo código em 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 registro em 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:

• Carrega a configuração do host de variáveis de ambiente prefixadas com ASPNETCORE_.
• Define o servidor Kestrel como o servidor Web e configura-o usando provedores de configuração de hospedagem do aplicativo. Para obter as opções padrão do servidor Kestrel, confira Configurar opções para o servidor Web Kestrel do ASP.NET Core.
• Adiciona middleware de filtragem de Host.
• Adiciona o Middleware de Cabeçalhos Encaminhados se ASPNETCORE_FORWARDEDHEADERS_ENABLED for igual a true.
• Habilita a integração de IIS. Para obter as opções padrão do IIS, confira Hospedar o ASP.NET Core no Windows com o ISS.

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:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment/IWebHostEnvironment

Para obter mais informações sobre serviços fornecidos pela estrutura, confira Injeção de dependência no 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, que permite que os aplicativos solicitem um desligamento normal.

Ao executar um desligamento normal, o host:

• Dispara os manipuladores de eventos ApplicationStopping, 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 manipuladores de eventos ApplicationStopped, 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 de eventos IHostApplicationLifetime:

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:

• Escuta Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM e chama StopApplication para iniciar o processo de desligamento.
• Desbloqueia extensões como RunAsync e WaitForShutdownAsync.

IHostEnvironment

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

• ApplicationName
• EnvironmentName
• ContentRootPath

Os aplicativos Web implementam a interface IWebHostEnvironment, que herda IHostEnvironment e adiciona 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 HostBuilderContext.Configuration dentro de ConfigureAppConfiguration. 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 o prefixo DOTNET_ e os argumentos de 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 pelo 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 prefixo DOTNET_ ou ASPNETCORE_, que aparece na lista de configurações a seguir como o espaço reservado {PREFIX_}. Para obter mais informações, consulte a seção Configurações do construtor padrão e Configuração: variáveis de ambiente.

ApplicationName

A propriedade IHostEnvironment.ApplicationName é definida na 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 propriedade IHostEnvironment.ContentRootPath determina onde o host começa a procurar por 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("/path/to/content/root")
    // ...

Para obter mais informações, consulte:

• Conceitos básicos: raiz de conteúdo
• WebRoot

EnvironmentName

A propriedade IHostEnvironment.EnvironmentName 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 é 30 segundos. Durante o período de tempo limite, o host:

• Gatilhos IHostApplicationLifetime.ApplicationStopping.
• Tenta parar os serviços hospedados, registrando em log os erros dos serviços que falham ao parar.

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: 30 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 chave hostBuilder:reloadConfigOnChange 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 dois-pontos : não funciona com chaves hierárquicas de variáveis 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 prefixo DOTNET_ ou ASPNETCORE_, que aparece na lista de configurações a seguir como o espaço reservado {PREFIX_}.

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 é false, a menos que o aplicativo seja executado com Kestrel por atrá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

Defina a porta HTTPS para a qual redirecionar se você obtiver uma conexão não HTTPS. Uso em aplicação de HTTPS. Essa configuração não faz com que o servidor escute na porta especificada. Ou seja, é possível redirecionar acidentalmente as solicitações para uma porta não utilizada.

Chave: https_portTipo: string
Padrão: um valor padrão não está 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");

HTTPS_Ports

As portas nas quais ouvir as conexões HTTPS.

Chave: https_ports
Tipo: string
Padrão: um valor padrão não está definido.
Variável de ambiente: {PREFIX_}HTTPS_PORTS

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

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

PreferHostingUrls

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

Chave: preferHostingUrls
Tipo: bool (true/1 ou false/0)
Padrão: false
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 as mensagens de status de inicialização de hospedagem.

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

O Kestrel tem sua própria API de configuração de ponto de extremidade. Para obter mais informações, confira Configurar pontos de extremidade para o servidor Web Kestrel do 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:

• Conceitos básicos: raiz da Web
• ContentRoot

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 implementações de IHostedService que são registradas no contêiner de serviço.

A diferença entre os métodos Run* e Start* é que os métodos Run* aguardam a conclusão do host para serem retornados, enquanto os métodos Start* são retornados imediatamente. Normalmente, os métodos Run* são usados em aplicativos de console, enquanto os métodos Start* são usados em serviços de execução longa.

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 do console, compila e inicia o host e aguarda Ctrl+C/SIGINT (Windows), ⌘+C (macOS) ou SIGTERM 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é que seja 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 por IHostLifetime, por exemplo, 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.

Recursos adicionais

• Tarefas em segundo plano com serviços hospedados no ASP.NET Core
• Link do GitHub para a origem do Host Genérico

  Observação

  Os links de documentação para a fonte de referência do .NET geralmente carregam o branch padrão do repositório, que representa o desenvolvimento atual da próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).