Compartilhar via


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

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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:

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

IHostEnvironment

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

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:

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:

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:

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.

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

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 do 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 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:

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

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

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

Para obter mais informações, consulte:

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 é 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 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:

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

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

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

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:

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.

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

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

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

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

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

// 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 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 configuração a seguir como o espaço reservado {PREFIX_}.

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

Para obter mais informações, consulte:

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

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

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

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 servidor Web Kestrel no 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 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.

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