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 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, consulte 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, consulte Host Genérico do .NET.

Definição do anfitrião

Um host é um objeto que encapsula os recursos de uma aplicação, como:

• Injeção de dependência (DI)
• Registo
• Configuração
• IHostedService implementações

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

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

Configurar um anfitrião

O host é normalmente configurado, criado 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 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 padrão do construtor

O método CreateDefaultBuilder:

• Define a raiz de conteúdo para 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 de usuário quando o aplicativo é executado no ambiente Development.
  • Variáveis de ambiente.
  • Argumentos de linha de comando.
• Adiciona os seguintes provedores de de log:
  • Consola
  • Depurar
  • EventSource (Fonte de eventos)
  • EventLog (somente quando executado no Windows)
• Permite validação de escopo e validação de dependência quando o ambiente está em Desenvolvimento.

O método ConfigureWebHostDefaults:

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

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

Serviços fornecidos pelo quadro estrutural

Os seguintes serviços são registados automaticamente:

• IHostApplicationLifetime
• IHostLifetime
• IHostEnvironment / IWebHostEnvironment

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

IHostApplicationLifetime

Injete o serviço IHostApplicationLifetime (anteriormente IApplicationLifetime) em qualquer classe para lidar com tarefas 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 início de aplicativo e parada de aplicativo. A interface também inclui um método StopApplication, que permite que os aplicativos solicitem um desligamento normal.

Ao executar um desligamento controlado, o host:

• Aciona 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 desativa novas conexões. O servidor aguarda a conclusão de solicitações em conexões existentes pelo tempo que o tempo limite de desligamento permitir. O servidor envia o cabeçalho de fechamento de conexão para solicitações adicionais em conexões existentes.
• Aciona 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 IHostApplicationLifetime manipuladores 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 para. É utilizada a última implementação registada.

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

• Ouve Ctrl+C/SIGINT (Windows), Ctrl+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:

• Nome da Aplicação
• EnvironmentName
• CaminhoRaizDeConteúdo

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

Configuração do host

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

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

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

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

O exemplo a seguir cria a configuração do 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 do aplicativo é criada chamando ConfigureAppConfiguration no IHostBuilder. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos. O aplicativo usa qualquer opção que defina um valor por último em uma determinada chave.

A configuração criada pela 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 aplicativos

Esta seção lista as configurações de host que se aplicam a cargas de trabalho HTTP e 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 aparecem na lista de configurações a seguir como o espaço reservado {PREFIX_}. Para obter mais informações, consulte a seção Configurações padrão do construtor e Configuração: variáveis de ambiente.

Nome do aplicativo

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

Principais: applicationName
Tipo: string
padrão: o nome do assembly que contém o ponto de entrada da aplicação.
Variável 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 arquivos de conteúdo. Se o caminho não existir, o host não será iniciado.

Tecla: contentRoot
Tipo: string
padrão: a pasta onde reside o assembly do aplicativo.
Variável de Ambiente: {PREFIX_}CONTENTROOT

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

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

Para mais informações, consulte:

• Fundamentos: Raiz de conteúdo
• WebRoot

Nome_do_ambiente

A propriedade IHostEnvironment.EnvironmentName pode ser definida como qualquer valor. Os valores definidos pela estrutura incluem Development, Staginge Production. Valores não são sensíveis a maiúsculas e minúsculas.

Principais: environment
Tipo: string
Default: Production
Variável Ambiente: {PREFIX_}ENVIRONMENT

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

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

Tempo de Espera para Encerramento

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

• Os gatilhos IHostApplicationLifetime.ApplicationStopping.
• Tentativas de parar serviços hospedados, registrando erros para serviços que não conseguem parar.

Se o período de tempo limite expirar antes de todos os serviços hospedados pararem, todos os serviços ativos restantes serão interrompidos quando o aplicativo for desligado. Os serviços param mesmo que não tenham terminado o processamento. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.

Principais: shutdownTimeoutSeconds
Tipo: int
padrão: 30 segundos
Variável 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);
        });
    });

Desativar recarga da configuração da aplicação quando ocorrer alterações.

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

Principais: hostBuilder:reloadConfigOnChange
Tipo: bool (true ou false)
padrão : true
Argumento de linha de comando: hostBuilder:reloadConfigOnChange
Variável Ambiente: {PREFIX_}hostBuilder:reloadConfigOnChange

Advertência

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

Configurações para aplicativos Web

Algumas configurações de host se aplicam apenas 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 aparecem 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 assumem webBuilder é uma instância de IWebHostBuilder, como no exemplo a seguir:

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

CapturarErrosDeInicialização

Quando false, erros durante a inicialização resultam na saída do host. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.

Principais: captureStartupErrors
Tipo: bool (true/1 ou false/0)
padrão: o padrão é false a menos que o aplicativo seja executado com Kestrel atrás do IIS, onde o padrão é true.
Variável Ambiente: {PREFIX_}CAPTURESTARTUPERRORS

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

webBuilder.CaptureStartupErrors(true);

Erros Detalhados

Quando ativado, ou quando o ambiente é Development, o aplicativo captura erros detalhados.

Principais: 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 chame UseSetting:

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

HostingStartupAssemblies

Uma cadeia de caracteres delimitada por ponto-e-vírgula contendo assemblies de inicialização a carregar no arranque. Embora o valor de configuração seja predefinido para uma string vazia, os assemblies de inicialização de hospedagem incluem sempre o assembly da aplicação. Quando os assemblies de inicialização de hospedagem são fornecidos, eles são adicionados ao assembly do aplicativo para serem carregados quando o aplicativo configura os seus serviços comuns durante a inicialização.

Principais: hostingStartupAssemblies
Tipo: string
Default: String vazia
Variável Ambiente: {PREFIX_}HOSTINGSTARTUPASSEMBLIES

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

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

HostingStartupExcludeAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula que especifica as assemblies de inicialização a excluir no arranque.

Key: hostingStartupExcludeAssemblies
Tipo: string
Default: String vazia
Variável de Ambiente: {PREFIX_}HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

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

HTTPS_Port

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

Key: https_portTipo: string
Padrão: Um valor padrão não está definido.
Variável Ambiente: {PREFIX_}HTTPS_PORT

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

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

Portas_HTTPS

As portas para escutar conexões HTTPS.

Principais: 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 chame UseSetting:

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

PreferHostingUrls

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

Principais: 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 chame PreferHostingUrls:

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

Previna o carregamento automático de assemblies de arranque de hospedagem, incluindo aqueles configurados pelo assembly da aplicação. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Principais: preventHostingStartup
Tipo: bool (true/1 ou false/0)
Default: false
Variável de Ambiente: {PREFIX_}PREVENTHOSTINGSTARTUP

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

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

StartupAssembly

A montagem para procurar a classe Startup.

Principais: startupAssembly
Tipo: string
padrão: a montagem do aplicativo
Variável Ambiente: {PREFIX_}STARTUPASSEMBLY

Para definir esse valor, use a variável de ambiente ou chame UseStartup. UseStartup pode ter 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>();

SuprimirMensagensDeEstado

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

Principais: suppressStatusMessages
Tipo: bool (true/1 ou false/0)
padrão : false
Variável Ambiente: {PREFIX_}SUPPRESSSTATUSMESSAGES

Para definir esse valor, use a configuração ou chame 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 de host usando a porta e o protocolo especificados (por exemplo, http://*:5000). O protocolo (http:// ou https://) deve ser incluído em cada URL. Os formatos suportados variam entre servidores.

Principais: 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 chame UseUrls:

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

Kestrel tem a sua própria API de configuração de endpoint. Para obter mais informações, consulte Configurar endpoints para o servidor Web ASP.NET Core Kestrel.

Raiz da Web

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

Principais: webroot
Tipo: string
Default: 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 chame UseWebRoot em IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para mais informações, consulte:

• Fundamentos: Raiz da Web
• RaizDeConteúdo

Gerenciar o tempo de vida do host

Chame métodos na implementação IHost construída para iniciar e parar a aplicação. Esses métodos afetam todas as implementações de IHostedService 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 antes de retornar, enquanto os métodos Start* retornam imediatamente. Os métodos Run* são normalmente usados em aplicativos de console, enquanto os métodos Start* são normalmente usados em serviços de longa execução.

Correr

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

RunAsync

RunAsync executa a aplicação e retorna um Task que se completa quando o token de cancelamento ou encerramento é acionado.

RunConsoleAsync

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

Início

Start inicia o host de forma síncrona.

StartAsync

StartAsync inicia o host e retorna um Task que é finalizado quando o token de cancelamento ou o encerramento é ativado.

WaitForStartAsync é chamado no início de StartAsync, que espera até que esteja completo antes de continuar. Este 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 acionado pelo IHostLifetime, como por meio de Ctrl+C/SIGINT (Windows), Ctrl+C (macOS) ou SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é acionado através do token fornecido e chama StopAsync.

Recursos adicionais

• Tarefas em segundo plano com serviços hospedados no ASP.NET Core
• Link do GitHub para o código fonte do Host Genérico

  Observação

  Os links de documentação para a fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma tag para uma versão específica, utilize o menu suspenso para alternar entre ramificações ou tags. Para obter mais informações, consulte Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).