Host Genérico .NET.NET Generic Host

Este artigo apresenta o Host Genérico do .NET Core (HostBuilder) e fornece diretrizes sobre como usá-lo.This article introduces the .NET Core Generic Host (HostBuilder) and provides guidance on how to use it.

O que é um host?What's a host?

Um host é um objeto que encapsula os recursos de um aplicativo, tais como:A host is an object that encapsulates an app's resources, such as:

  • DI (injeção de dependência)Dependency injection (DI)
  • Registrando em logLogging
  • ConfiguraçãoConfiguration
  • Implementações de IHostedServiceIHostedService implementations

Quando um host é iniciado, ele chama IHostedService.StartAsync em cada implementação de IHostedService que encontra no contêiner de injeção de dependência.When a host starts, it calls IHostedService.StartAsync on each implementation of IHostedService that it finds in the DI container. Em um aplicativo Web, uma das implementações de IHostedService é um serviço Web que inicia uma implementação do servidor HTTP.In a web app, one of the IHostedService implementations is a web service that starts an HTTP server implementation.

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.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Em versões do ASP.NET Core anteriores à 3.0, o host da Web é usado para cargas de trabalho HTTP.In versions of ASP.NET Core earlier than 3.0, the Web Host is used for HTTP workloads. O host da Web não é mais recomendado para aplicativos Web e permanece disponível somente para compatibilidade com versões anteriores.The Web Host is no longer recommended for web apps and remains available only for backward compatibility.

Configurar um hostSet up a host

O host normalmente é configurado, compilado e executado pelo código na classe Program.The host is typically configured, built, and run by code in the Program class. O método Main:The Main method:

  • Chama um método CreateHostBuilder para criar e configurar um objeto construtor.Calls a CreateHostBuilder method to create and configure a builder object.
  • Chama os métodos Build e Run no objeto construtor.Calls Build and Run methods on the builder object.

Eis aqui o código Program.cs para uma carga de trabalho não HTTP, com uma única implementação de IHostedService adicionada ao contêiner de injeção de dependência.Here's Program.cs code for a non-HTTP workload, with a single IHostedService implementation added to the DI container.

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:For an HTTP workload, the Main method is the same but CreateHostBuilder calls 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.If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method. 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.The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without running the app. Para obter mais informações, confira Criação de DbContext no tempo de design.For more information, see Design-time DbContext Creation.

Configurações do construtor padrãoDefault builder settings

O método CreateDefaultBuilder:The CreateDefaultBuilder method:

  • Define a raiz do conteúdo como o caminho retornado por GetCurrentDirectory.Sets the content root to the path returned by GetCurrentDirectory.
  • Carrega a configuração do host de:Loads host configuration from:
    • Variáveis de ambiente prefixadas com "DOTNET_".Environment variables prefixed with "DOTNET_".
    • Argumentos de linha de comando.Command-line arguments.
  • Carrega a configuração do aplicativo de:Loads app configuration from:
    • appsettings.json.appsettings.json.
    • appsettings.{Environment}.json.appsettings.{Environment}.json.
    • Gerenciador de Segredo quando o aplicativo é executado no ambiente Development.Secret Manager when the app runs in the Development environment.
    • Variáveis de ambiente.Environment variables.
    • Argumentos de linha de comando.Command-line arguments.
  • Adiciona os seguintes provedores de registro em log:Adds the following logging providers:
    • ConsoleConsole
    • DepurarDebug
    • EventSourceEventSource
    • EventLog (somente quando em execução no Windows)EventLog (only when running on Windows)
  • Habilita a validação de escopo e a validação de dependência quando o ambiente é o de Desenvolvimento.Enables scope validation and dependency validation when the environment is Development.

O método ConfigureWebHostDefaults:The ConfigureWebHostDefaults method:

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.The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

Serviços fornecidos pela estruturaFramework-provided services

Serviços que são registradosautomaticamente incluem o seguinte:Services that are registered automatically include the following:

Para obter uma lista de todos os serviços fornecidos pela estrutura, consulte Injeção de dependência no ASP.NET Core.For a list of all framework-provided services, see Injeção de dependência no ASP.NET Core.

IHostApplicationLifetimeIHostApplicationLifetime

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.Inject the IHostApplicationLifetime (formerly IApplicationLifetime) service into any class to handle post-startup and graceful shutdown tasks. 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.Three properties on the interface are cancellation tokens used to register app start and app stop event handler methods. A interface também inclui um método StopApplication.The interface also includes a StopApplication method.

O exemplo a seguir é uma implementação IHostedService que registra os eventos IApplicationLifetime:The following example is an IHostedService implementation that registers the IApplicationLifetime events:

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

IHostLifetimeIHostLifetime

A implementação IHostLifetime controla quando o host é iniciado e quando ele é interrompido.The IHostLifetime implementation controls when the host starts and when it stops. A última implementação registrada é usada.The last implementation registered is used.

ConsoleLifetime é a implementação IHostLifetime padrão.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:ConsoleLifetime:

IHostEnvironmentIHostEnvironment

Injete o serviço IHostEnvironment em uma classe para obter informações sobre o seguinte:Inject the IHostEnvironment service into a class to get information about the following:

Os aplicativos Web implementam a interface IWebHostEnvironment, que herda IHostEnvironment e adiciona:Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds:

Configuração do hostHost configuration

A configuração do host é usada para as propriedades da implementação IHostEnvironment.Host configuration is used for the properties of the IHostEnvironment implementation.

A configuração do host está disponível por meio de HostBuilderContext.Configuration dentro de ConfigureAppConfiguration.Host configuration is available from HostBuilderContext.Configuration inside ConfigureAppConfiguration. Após ConfigureAppConfiguration, HostBuilderContext.Configuration é substituído com a configuração do aplicativo.After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

Para adicionar a configuração do host, chame ConfigureHostConfiguration em IHostBuilder.To add host configuration, call ConfigureHostConfiguration on IHostBuilder. ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos.ConfigureHostConfiguration can be called multiple times with additive results. O host usa a opção que define um valor por último em uma chave determinada.The host uses whichever option sets a value last on a given key.

O provedor de variável de ambiente com o prefixo DOTNET_ e os argumentos de linha de comando são incluídos pelo CreateDefaultBuilder.The environment variable provider with prefix DOTNET_ and command line args are included by CreateDefaultBuilder. Para aplicativos Web, o provedor de variáveis de ambiente com o prefixo ASPNETCORE_ é adicionado.For web apps, the environment variable provider with prefix ASPNETCORE_ is added. O prefixo é removido quando as variáveis de ambiente são lidas.The prefix is removed when the environment variables are read. 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.For example, the environment variable value for ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

O exemplo a seguir cria a configuração de host:The following example creates host 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 aplicativoApp configuration

A configuração de aplicativo é criada chamando ConfigureAppConfiguration em IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on IHostBuilder. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos.ConfigureAppConfiguration can be called multiple times with additive results. O aplicativo usa a opção que define um valor por último em uma chave determinada.The app uses whichever option sets a value last on a given key.

A configuração criada pelo ConfigureAppConfiguration está disponível em HostBuilderContext.Configuration para operações subsequentes e como um serviço da DI.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and as a service from DI. A configuração do host também é adicionada à configuração do aplicativo.The host configuration is also added to the app configuration.

Para obter mais informações, consulte Configuração no ASP.NET Core.For more information, see Configuration in ASP.NET Core.

Configurações para todos os tipos de aplicativoSettings for all app types

Esta seção lista as configurações de host que se aplicam a cargas de trabalho HTTP e àquelas não HTTP.This section lists host settings that apply to both HTTP and non-HTTP workloads. Por padrão, variáveis de ambiente usadas para definir essas configurações podem ter um prefixo DOTNET_ ou ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

ApplicationNameApplicationName

A propriedade IHostEnvironment.ApplicationName é definida na configuração do host durante a construção do host.The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

Chave: applicationNameKey: applicationName
Tipo: stringType: string
Padrão: O nome do assembly que contém o ponto de entrada do aplicativo.Default: The name of the assembly that contains the app's entry point. Variável de ambiente: <PREFIX_>APPLICATIONNAMEEnvironment variable: <PREFIX_>APPLICATIONNAME

Para definir esse valor, use a variável de ambiente.To set this value, use the environment variable.

ContentRootPathContentRootPath

A propriedade IHostEnvironment.ContentRootPath determina o local em que o host começa a procurar por arquivos de conteúdo.The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. Se o caminho não existir, o host não será iniciado.If the path doesn't exist, the host fails to start.

Chave: contentRootKey: contentRoot
Tipo: stringType: string
Padrão: A pasta em que o assembly do aplicativo reside.Default: The folder where the app assembly resides.
Variável de ambiente: <PREFIX_>CONTENTROOTEnvironment variable: <PREFIX_>CONTENTROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseContentRoot em IHostBuilder:To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

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

EnvironmentNameEnvironmentName

A propriedade IHostEnvironment.EnvironmentName pode ser definida para qualquer valor.The IHostEnvironment.EnvironmentName property can be set to any value. Os valores definidos pela estrutura incluem Development, Staging e Production.Framework-defined values include Development, Staging, and Production. Os valores não diferenciam maiúsculas de minúsculas.Values aren't case sensitive.

Chave: ambienteKey: environment
Tipo: stringType: string
Padrão: ProduçãoDefault: Production
Variável de ambiente: <PREFIX_>ENVIRONMENTEnvironment variable: <PREFIX_>ENVIRONMENT

Para definir esse valor, use a variável de ambiente ou a chamada UseEnvironment em IHostBuilder:To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

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

ShutdownTimeoutShutdownTimeout

HostOptions.ShutdownTimeout define o tempo limite para StopAsync.HostOptions.ShutdownTimeout sets the timeout for StopAsync. O valor padrão é cinco segundos.The default value is five seconds. Durante o período de tempo limite, o host:During the timeout period, the 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.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. Os serviços serão parados mesmo se ainda não tiverem concluído o processamento.The services stop even if they haven't finished processing. Se os serviços exigirem mais tempo para parar, aumente o tempo limite.If services require additional time to stop, increase the timeout.

Chave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Padrão: Variável de ambiente de cinco segundos: <PREFIX_>SHUTDOWNTIMEOUTSECONDSDefault: 5 seconds Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

Para definir esse valor, use a variável de ambiente ou configure HostOptions.To set this value, use the environment variable or configure HostOptions. O exemplo a seguir define o tempo limite para 20 segundos:The following example sets the timeout to 20 seconds:

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

Configurações para aplicativos WebSettings for web apps

Algumas configurações de host se aplicam somente a cargas de trabalho HTTP.Some host settings apply only to HTTP workloads. Por padrão, variáveis de ambiente usadas para definir essas configurações podem ter um prefixo DOTNET_ ou ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

Métodos de extensão em IWebHostBuilder estão disponíveis para essas configurações.Extension methods on IWebHostBuilder are available for these settings. 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:Code samples that show how to call the extension methods assume webBuilder is an instance of IWebHostBuilder, as in the following example:

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

CaptureStartupErrorsCaptureStartupErrors

Quando false, erros durante a inicialização resultam no encerramento do host.When false, errors during startup result in the host exiting. Quando true, o host captura exceções durante a inicialização e tenta iniciar o servidor.When true, the host captures exceptions during startup and attempts to start the server.

Chave: captureStartupErrorsKey: captureStartupErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: o padrão é false, a menos que o aplicativo seja executado com o Kestrel por trás do IIS, em que o padrão é true.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Variável de ambiente: <PREFIX_>CAPTURESTARTUPERRORSEnvironment variable: <PREFIX_>CAPTURESTARTUPERRORS

Para definir esse valor, use a configuração ou a chamada CaptureStartupErrors:To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrorsDetailedErrors

Quando habilitado (ou quando o ambiente é Development), o aplicativo captura erros detalhados.When enabled, or when the environment is Development, the app captures detailed errors.

Chave: detailedErrorsKey: detailedErrors
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Variável de ambiente: <PREFIX_>_DETAILEDERRORSEnvironment variable: <PREFIX_>_DETAILEDERRORS

Para definir esse valor, use a configuração ou a chamada UseSetting:To set this value, use configuration or call UseSetting:

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

HostingStartupAssembliesHostingStartupAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para carregamento na inicialização.A semicolon-delimited string of hosting startup assemblies to load on startup. 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.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

Chave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: stringType: string
Padrão: Cadeia de caracteres vaziaDefault: Empty string
Variável de ambiente: <PREFIX_>_HOSTINGSTARTUPASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:To set this value, use configuration or call UseSetting:

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

HostingStartupExcludeAssembliesHostingStartupExcludeAssemblies

Uma cadeia de caracteres delimitada por ponto e vírgula de assemblies de inicialização de hospedagem para exclusão na inicialização.A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Chave: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Tipo: stringType: string
Padrão: Cadeia de caracteres vaziaDefault: Empty string
Variável de ambiente: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para definir esse valor, use a configuração ou a chamada UseSetting:To set this value, use configuration or call UseSetting:

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

HTTPS_PortHTTPS_Port

A porta de redirecionamento HTTPS.The HTTPS redirect port. Uso em aplicação de HTTPS.Used in enforcing HTTPS.

Chave: https_portKey: https_port
Tipo: stringType: string
Padrão: um valor padrão não está definido.Default: A default value isn't set.
Variável de ambiente: <PREFIX_>HTTPS_PORTEnvironment variable: <PREFIX_>HTTPS_PORT

Para definir esse valor, use a configuração ou a chamada UseSetting:To set this value, use configuration or call UseSetting:

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

PreferHostingUrlsPreferHostingUrls

Indica se o host deve escutar as URLs configuradas com o IWebHostBuilder em vez daquelas configuradas com a implementação IServer.Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those configured with the IServer implementation.

Chave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: trueDefault: true
Variável de ambiente: <PREFIX_>_PREFERHOSTINGURLSEnvironment variable: <PREFIX_>_PREFERHOSTINGURLS

Para definir esse valor, use a variável de ambiente ou a chamada PreferHostingUrls:To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartupPreventHostingStartup

Impede o carregamento automático de assemblies de inicialização de hospedagem, incluindo assemblies de inicialização de hospedagem configurados pelo assembly do aplicativo.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Para obter mais informações, consulte Usar assemblies de inicialização de hospedagem no ASP.NET Core.For more information, see Usar assemblies de inicialização de hospedagem no ASP.NET Core.

Chave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true ou 1)Type: bool (true or 1)
Padrão: falsoDefault: false
Variável de ambiente: <PREFIX_>_PREVENTHOSTINGSTARTUPEnvironment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

Para definir esse valor, use a variável de ambiente ou a chamada UseSetting:To set this value, use the environment variable or call UseSetting :

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

StartupAssemblyStartupAssembly

O assembly no qual pesquisar pela classe Startup.The assembly to search for the Startup class.

Chave: startupAssemblyKey: startupAssembly
Tipo: stringType: string
Padrão: o assembly do aplicativoDefault: The app's assembly
Variável de ambiente: <PREFIX_>STARTUPASSEMBLYEnvironment variable: <PREFIX_>STARTUPASSEMBLY

Para definir esse valor, use a variável de ambiente ou a chamada UseStartup.To set this value, use the environment variable or call UseStartup. UseStartup pode usar um nome de assembly (string) ou um tipo (TStartup).UseStartup can take an assembly name (string) or a type (TStartup). Se vários métodos UseStartup forem chamados, o último terá precedência.If multiple UseStartup methods are called, the last one takes precedence.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

URLsURLs

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.A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should listen on for requests. Por exemplo, http://localhost:123.For example, 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).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). O protocolo (http:// ou https://) deve ser incluído com cada URL.The protocol (http:// or https://) must be included with each URL. Os formatos compatíveis variam dependendo dos servidores.Supported formats vary among servers.

Chave: urlsKey: urls
Tipo: stringType: string
Padrão: http://localhost:5000 ehttps://localhost:5001Default: http://localhost:5000 and https://localhost:5001
Variável de ambiente: <PREFIX_>URLSEnvironment variable: <PREFIX_>URLS

Para definir esse valor, use a variável de ambiente ou a chamada UseUrls:To set this value, use the environment variable or call 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.Kestrel has its own endpoint configuration API. Para obter mais informações, consulte Implementação do servidor Web Kestrel no ASP.NET Core.For more information, see Implementação do servidor Web Kestrel no ASP.NET Core.

WebRootWebRoot

O caminho relativo para os ativos estáticos do aplicativo.The relative path to the app's static assets.

Chave: webrootKey: webroot
Tipo: stringType: string
Padrão: (Raiz de conteúdo)/wwwroot se o caminho existir.Default: (Content Root)/wwwroot, if the path exists. Se o caminho não existir, um provedor de arquivo não operacional será usado.If the path doesn't exist, a no-op file provider is used.
Variável de ambiente: <PREFIX_>WEBROOTEnvironment variable: <PREFIX_>WEBROOT

Para definir esse valor, use a variável de ambiente ou a chamada UseWebRoot:To set this value, use the environment variable or call UseWebRoot:

webBuilder.UseWebRoot("public");

Gerenciar o tempo de vida do hostManage the host lifetime

Chame métodos na implementação de IHost criada para iniciar e parar o aplicativo.Call methods on the built IHost implementation to start and stop the app. Esses métodos afetam todas as implementações de IHostedService que são registradas no contêiner de serviço.These methods affect all IHostedService implementations that are registered in the service container.

ExecutarRun

Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado.Run runs the app and blocks the calling thread until the host is shut down.

RunAsyncRunAsync

RunAsync executa o aplicativo e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered.

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync habilita o suporte do console, compila e inicia o host e aguarda Ctrl + C/SIGINT ou SIGTERM desligar.RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

InícioStart

Start inicia o host de forma síncrona.Start starts the host synchronously.

StartAsyncStartAsync

StartAsync inicia o host e retorna um Task, que é concluído quando o token de cancelamento ou o desligamento é disparado.StartAsync starts the host and returns a Task that completes when the cancellation token or shutdown is triggered.

WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído antes de continuar.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. Isso pode ser usado para atrasar a inicialização até que seja sinalizado por um evento externo.This can be used to delay startup until signaled by an external event.

StopAsyncStopAsync

StopAsync tenta parar o host dentro do tempo limite fornecido.StopAsync attempts to stop the host within the provided timeout.

WaitForShutdownWaitForShutdown

WaitForShutdown bloqueia o thread de chamada até que o desligamento seja disparado por IHostLifetime, por exemplo, por meio de Ctrl + C/SIGINT ou SIGTERM.WaitForShutdown blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via Ctrl+C/SIGINT or SIGTERM.

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do token fornecido e chama StopAsync.WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

Controle externoExternal control

O controle direto do tempo de vida do host pode ser obtido usando os métodos que podem ser chamados externamente:Direct control of the host lifetime can be achieved using methods that can be called externally:

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

Aplicativos ASP.NET Core configuram e iniciam um host.ASP.NET Core apps configure and launch a host. O host é responsável pelo gerenciamento de tempo de vida e pela inicialização do aplicativo.The host is responsible for app startup and lifetime management.

Este artigo aborda o Host Genérico do ASP.NET Core (HostBuilder), que é usado para hospedar aplicativos que não processam solicitações HTTP.This article covers the ASP.NET Core Generic Host (HostBuilder), which is used for apps that don't process HTTP requests.

A finalidade do Host Genérico é separar o pipeline HTTP da API de host da Web para permitir maior gama de cenários de host.The purpose of Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of host scenarios. Sistema de mensagens, tarefas em segundo plano e outras cargas de trabalho não HTTP com base no benefício do Host Genérico de recursos em paralelo, como configuração, DI (injeção de dependência) e log.Messaging, background tasks, and other non-HTTP workloads based on Generic Host benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

O Host Genérico é novo no ASP.NET Core 2.1 e não é adequado para cenários de hospedagem na Web.Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. Para cenários de hospedagem na Web, use o host da Web.For web hosting scenarios, use the Web Host. O Host Genérico substituirá o host da Web em uma versão futura e atuar como API do host principal em cenários HTTP e não HTTP.Generic Host will replace Web Host in a future release and act as the primary host API in both HTTP and non-HTTP scenarios.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Ao executar o aplicativo de exemplo no Visual Studio Code, use um terminal externo ou integrado.When running the sample app in Visual Studio Code, use an external or integrated terminal. Não execute o exemplo em um internalConsole.Don't run the sample in an internalConsole.

Para definir o console no Visual Studio Code:To set the console in Visual Studio Code:

  1. Abra o arquivo .vscode/launch.json.Open the .vscode/launch.json file.
  2. Na configuração Inicialização do .NET Core (console) , localize a entrada console.In the .NET Core Launch (console) configuration, locate the console entry. Defina o valor como externalTerminal ou integratedTerminal.Set the value to either externalTerminal or integratedTerminal.

IntroduçãoIntroduction

A biblioteca do Host Genérico está disponível no namespace Microsoft.Extensions.Hosting e é fornecida pelo pacote Microsoft.Extensions.Hosting.The Generic Host library is available in the Microsoft.Extensions.Hosting namespace and provided by the Microsoft.Extensions.Hosting package. O pacote Microsoft.Extensions.Hosting está incluído no metapacote Microsoft.AspNetCore.App (ASP.NET Core 2.1 ou posterior).The Microsoft.Extensions.Hosting package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

IHostedService é o ponto de entrada para a execução de código.IHostedService is the entry point to code execution. Cada implementação do IHostedService é executada na ordem do registro de serviço em ConfigureServices.Each IHostedService implementation is executed in the order of service registration in ConfigureServices. StartAsync é chamado em cada IHostedService quando o host é iniciado e StopAsync é chamado na ordem inversa de registro quando o host é desligado normalmente.StartAsync is called on each IHostedService when the host starts, and StopAsync is called in reverse registration order when the host shuts down gracefully.

Configurar um hostSet up a host

IHostBuilder é o principal componente usado por aplicativos e bibliotecas para inicializar, compilar e executar o host:IHostBuilder is the main component that libraries and apps use to initialize, build, and run the host:

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

    await host.RunAsync();
}

OpçõesOptions

Os HostOptions configuram opções para o IHost.HostOptions configure options for the IHost.

Tempo limite de desligamentoShutdown timeout

O ShutdownTimeout define o tempo limite para StopAsync.ShutdownTimeout sets the timeout for StopAsync. O valor padrão é cinco segundos.The default value is five seconds.

A seguinte configuração de opção no Program.Main aumenta o tempo limite de desligamento padrão de cinco segundos para 20 segundos:The following option configuration in Program.Main increases the default five second shutdown timeout to 20 seconds:

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

Serviços padrãoDefault services

Os seguintes serviços são registrados durante a inicialização do host:The following services are registered during host initialization:

Configuração do hostHost configuration

A configuração do host é criada:Host configuration is created by:

Métodos de extensãoExtension methods

Chave do aplicativo (nome)Application key (name)

A propriedade IHostingEnvironment.ApplicationName é definida na configuração do host durante a construção do host.The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. Para definir o valor explicitamente, use o HostDefaults.ApplicationKey:To set the value explicitly, use the HostDefaults.ApplicationKey:

Chave: applicationNameKey: applicationName
Tipo: stringType: string
Padrão: o nome do assembly que contém o ponto de entrada do aplicativo.Default: The name of the assembly containing the app's entry point.
Definido usando: HostBuilderContext.HostingEnvironment.ApplicationNameSet using: HostBuilderContext.HostingEnvironment.ApplicationName
Variável de ambiente: <PREFIX_>APPLICATIONNAME (<PREFIX_> é opcional e definida pelo usuário)Environment variable: <PREFIX_>APPLICATIONNAME (<PREFIX_> is optional and user-defined)

Raiz do conteúdoContent root

Essa configuração determina onde o host começa a procurar por arquivos de conteúdo.This setting determines where the host begins searching for content files.

Chave: contentRootKey: contentRoot
Tipo: stringType: string
Padrão: o padrão é a pasta em que o assembly do aplicativo reside.Default: Defaults to the folder where the app assembly resides.
Definido usando: UseContentRootSet using: UseContentRoot
Variável de ambiente: <PREFIX_>CONTENTROOT (<PREFIX_> é opcional e definida pelo usuário)Environment variable: <PREFIX_>CONTENTROOT (<PREFIX_> is optional and user-defined)

Se o caminho não existir, o host não será iniciado.If the path doesn't exist, the host fails to start.

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

AmbienteEnvironment

Define o ambiente do aplicativo.Sets the app's environment.

Chave: ambienteKey: environment
Tipo: stringType: string
Padrão: ProduçãoDefault: Production
Definido usando: UseEnvironmentSet using: UseEnvironment
Variável de ambiente: <PREFIX_>ENVIRONMENT (<PREFIX_> é opcional e definida pelo usuário)Environment variable: <PREFIX_>ENVIRONMENT (<PREFIX_> is optional and user-defined)

O ambiente pode ser definido como qualquer valor.The environment can be set to any value. Os valores definidos pela estrutura incluem Development, Staging e Production.Framework-defined values include Development, Staging, and Production. Os valores não diferenciam maiúsculas de minúsculas.Values aren't case sensitive.

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

ConfigureHostConfigurationConfigureHostConfiguration

ConfigureHostConfiguration usa um IConfigurationBuilder para criar um IConfiguration para o host.ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. A configuração do host é usada para inicializar o IHostingEnvironment para uso no processo de build do aplicativo.The host configuration is used to initialize the IHostingEnvironment for use in the app's build process.

ConfigureHostConfiguration pode ser chamado várias vezes com resultados aditivos.ConfigureHostConfiguration can be called multiple times with additive results. O host usa a opção que define um valor por último em uma chave determinada.The host uses whichever option sets a value last on a given key.

Não há provedores incluídos por padrão.No providers are included by default. Você deve especificar explicitamente os provedores de configuração exigidos pelo aplicativo em ConfigureHostConfiguration, incluindo:You must explicitly specify whatever configuration providers the app requires in ConfigureHostConfiguration, including:

  • Configuração de arquivo (por exemplo, de um arquivo hostsettings.json).File configuration (for example, from a hostsettings.json file).
  • Configuração de variável de ambiente.Environment variable configuration.
  • Configuração de argumento de linha de comando.Command-line argument configuration.
  • Demais provedores de configuração necessários.Any other required configuration providers.

A configuração de arquivo do host é habilitada especificando o caminho base do aplicativo com SetBasePath seguido por uma chamada a um dos provedores de configuração do arquivo.File configuration of the host is enabled by specifying the app's base path with SetBasePath followed by a call to one of the file configuration providers. O aplicativo de exemplo usa um arquivo JSON, hostsettings.json, e chamadas AddJsonFile para consumir as definições de configuração de host do arquivo.The sample app uses a JSON file, hostsettings.json, and calls AddJsonFile to consume the file's host configuration settings.

Para adicionar uma configuração de variável de ambiente do host, chame AddEnvironmentVariables no construtor do host.To add environment variable configuration of the host, call AddEnvironmentVariables on the host builder. AddEnvironmentVariables aceita um prefixo opcional definido pelo usuário.AddEnvironmentVariables accepts an optional user-defined prefix. O aplicativo de exemplo usa um prefixo igual a PREFIX_.The sample app uses a prefix of PREFIX_. O prefixo é removido quando as variáveis de ambiente são lidas.The prefix is removed when the environment variables are read. Quando o host do aplicativo de exemplo é configurado, o valor da variável de ambiente de PREFIX_ENVIRONMENT torna-se o valor de configuração de host para a chave environment.When the sample app's host is configured, the environment variable value for PREFIX_ENVIRONMENT becomes the host configuration value for the environment key.

Durante o desenvolvimento, ao usar o Visual Studio ou executar um aplicativo com dotnet run, as variáveis de ambiente poderão ser definidas no arquivo Properties/launchSettings.json.During development when using Visual Studio or running an app with dotnet run, environment variables may be set in the Properties/launchSettings.json file. No Visual Studio Code, as variáveis de ambiente podem ser definidas no arquivo .vscode/launch.json durante o desenvolvimento.In Visual Studio Code, environment variables may be set in the .vscode/launch.json file during development. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

A configuração de linha de comando é adicionada chamando AddCommandLine.Command-line configuration is added by calling AddCommandLine. A configuração de linha de comando é adicionada por último para permitir que os argumentos de linha de comando substituam a configuração fornecida pelos provedores de configuração anteriores.Command-line configuration is added last to permit command-line arguments to override configuration provided by the earlier configuration providers.

hostsettings.json:hostsettings.json:

{
  "environment": "Development"
}

Configuração adicional pode ser fornecida com as chaves applicationName e contentRoot.Additional configuration can be provided with the applicationName and contentRoot keys.

Exemplo da configuração HostBuilder usando ConfigureHostConfiguration:Example HostBuilder configuration using ConfigureHostConfiguration:

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

ConfigureAppConfigurationConfigureAppConfiguration

A configuração de aplicativo é criada chamando ConfigureAppConfiguration na implementação IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on the IHostBuilder implementation. ConfigureAppConfiguration usa um IConfigurationBuilder para criar um IConfiguration para o aplicativo.ConfigureAppConfiguration uses an IConfigurationBuilder to create an IConfiguration for the app. ConfigureAppConfiguration pode ser chamado várias vezes com resultados aditivos.ConfigureAppConfiguration can be called multiple times with additive results. O aplicativo usa a opção que define um valor por último em uma chave determinada.The app uses whichever option sets a value last on a given key. A configuração criada pelo ConfigureAppConfiguration está disponível em HostBuilderContext.Configuration para operações subsequentes e em Services.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and in Services.

A configuração do aplicativo recebe automaticamente a configuração de host fornecida por ConfigureHostConfiguration.App configuration automatically receives host configuration provided by ConfigureHostConfiguration.

Exemplo da configuração de aplicativo usando ConfigureAppConfiguration:Example app configuration using ConfigureAppConfiguration:

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:appsettings.json:

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

appsettings.Development.json:appsettings.Development.json:

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

appsettings.Production.json:appsettings.Production.json:

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

Para mover arquivos de configurações para o diretório de saída, especifique os arquivos de configurações como itens de projeto do MSBuild no arquivo de projeto.To move settings files to the output directory, specify the settings files as MSBuild project items in the project file. O aplicativo de exemplo move os arquivos de configurações de aplicativo JSON e hostsettings.json com o seguinte item <Content>:The sample app moves its JSON app settings files and hostsettings.json with the following <Content> item:

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Observação

Métodos de extensão de configuração, como AddJsonFile e AddEnvironmentVariables, exigem pacotes adicionais do NuGet, como Microsoft.Extensions.Configuration.Json e Microsoft.Extensions.Configuration.EnvironmentVariables.Configuration extension methods, such as AddJsonFile and AddEnvironmentVariables require additional NuGet packages, such as Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Configuration.EnvironmentVariables. A menos que o aplicativo use o metapacote Microsoft.AspNetCore.App, esses pacotes devem ser adicionados ao projeto, além do pacote principal Microsoft.Extensions.Configuration.Unless the app uses the Microsoft.AspNetCore.App metapackage, these packages must be added to the project in addition to the core Microsoft.Extensions.Configuration package. Para obter mais informações, consulte Configuração no ASP.NET Core.For more information, see Configuração no ASP.NET Core.

ConfigureServicesConfigureServices

ConfigureServices adiciona serviços ao contêiner injeção de dependência do aplicativo.ConfigureServices adds services to the app's dependency injection container. ConfigureServices pode ser chamado várias vezes com resultados aditivos.ConfigureServices can be called multiple times with additive results.

Um serviço hospedado é uma classe com lógica de tarefa em segundo plano que implementa a interface IHostedService.A hosted service is a class with background task logic that implements the IHostedService interface. Para obter mais informações, consulte Tarefas em segundo plano com serviços hospedados no ASP.NET Core.For more information, see Tarefas em segundo plano com serviços hospedados no ASP.NET Core.

O aplicativo de exemplo usa o método de extensão AddHostedService para adicionar um serviço para eventos de tempo de vida, LifetimeEventsHostedService, e uma tarefa em segundo plano programada, TimedHostedService, para o aplicativo:The sample app uses the AddHostedService extension method to add a service for lifetime events, LifetimeEventsHostedService, and a timed background task, TimedHostedService, to the app:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLoggingConfigureLogging

ConfigureLogging adiciona um delegado para configurar o ILoggingBuilder fornecido.ConfigureLogging adds a delegate for configuring the provided ILoggingBuilder. ConfigureLogging pode ser chamado várias vezes com resultados aditivos.ConfigureLogging may be called multiple times with additive results.

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

UseConsoleLifetimeUseConsoleLifetime

UseConsoleLifetime escuta Ctrl + C/SIGINT ou SIGTERM e chama StopApplication para iniciar o processo de desligamento.UseConsoleLifetime listens for Ctrl+C/SIGINT or SIGTERM and calls StopApplication to start the shutdown process. UseConsoleLifetime desbloqueia extensões como RunAsync e WaitForShutdownAsync.UseConsoleLifetime unblocks extensions such as RunAsync and WaitForShutdownAsync. ConsoleLifetime é previamente registrado como a implementação de tempo de vida padrão.ConsoleLifetime is pre-registered as the default lifetime implementation. O último tempo de vida registrado é usado.The last lifetime registered is used.

var host = new HostBuilder()
    .UseConsoleLifetime()

Configuração do contêinerContainer configuration

Para dar suporte à conexão de outros contêineres, o host pode aceitar um IServiceProviderFactory<TContainerBuilder>.To support plugging in other containers, the host can accept an IServiceProviderFactory<TContainerBuilder>. O fornecimento de um alocador não faz parte do registro de contêiner de injeção de dependência, mas, em vez disso, um host intrínseco é usado para criar o contêiner de DI concreto.Providing a factory isn't part of the DI container registration but is instead a host intrinsic used to create the concrete DI container. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) substitui o alocador padrão usado para criar o provedor de serviços do aplicativo.UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to create the app's service provider.

A configuração de contêiner personalizado é gerenciada pelo método ConfigureContainer.Custom container configuration is managed by the ConfigureContainer method. ConfigureContainer fornece uma experiência fortemente tipada para configurar o contêiner sobre a API do host subjacente.ConfigureContainer provides a strongly-typed experience for configuring the container on top of the underlying host API. ConfigureContainer pode ser chamado várias vezes com resultados aditivos.ConfigureContainer can be called multiple times with additive results.

Crie um contêiner de serviço para o aplicativo:Create a service container for the app:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Forneça um alocador de contêiner de serviço:Provide a service container factory:

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

Use o alocador e configure o contêiner de serviço personalizado para o aplicativo:Use the factory and configure the custom service container for the app:

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

ExtensibilidadeExtensibility

Extensibilidade de host é executada com métodos de extensão em IHostBuilder.Host extensibility is performed with extension methods on IHostBuilder. O exemplo a seguir mostra como um método de extensão estende uma implementação do IHostBuilder com o exemplo do TimedHostedService, demonstrado no Tarefas em segundo plano com serviços hospedados no ASP.NET Core.The following example shows how an extension method extends an IHostBuilder implementation with the TimedHostedService example demonstrated in Tarefas em segundo plano com serviços hospedados no ASP.NET Core.

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

Um aplicativo estabelece o método de extensão UseHostedService para registrar o serviço hospedado passado no T:An app establishes the UseHostedService extension method to register the hosted service passed in T:

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

Gerenciar o hostManage the host

A implementação IHost é responsável por iniciar e parar as implementações IHostedService que estão registradas no contêiner de serviço.The IHost implementation is responsible for starting and stopping the IHostedService implementations that are registered in the service container.

ExecutarRun

Run executa o aplicativo e bloqueia o thread de chamada até que o host seja desligado:Run runs the app and blocks the calling thread until the host is shut down:

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

        host.Run();
    }
}

RunAsyncRunAsync

RunAsync executa o aplicativo e retorna um Task que é concluído quando o token de cancelamento ou o desligamento é disparado:RunAsync runs the app and returns a Task that completes when the cancellation token or shutdown is triggered:

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

        await host.RunAsync();
    }
}

RunConsoleAsyncRunConsoleAsync

RunConsoleAsync habilita o suporte do console, compila e inicia o host e aguarda Ctrl + C/SIGINT ou SIGTERM desligar.RunConsoleAsync enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

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

        await hostBuilder.RunConsoleAsync();
    }
}

Start e StopAsyncStart and StopAsync

Start inicia o host de forma síncrona.Start starts the host synchronously.

StopAsync tenta parar o host dentro do tempo limite fornecido.StopAsync attempts to stop the host within the provided timeout.

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

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync e StopAsyncStartAsync and StopAsync

StartAsync inicia o aplicativo.StartAsync starts the app.

StopAsync interrompe o aplicativo.StopAsync stops the app.

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

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

            await host.StopAsync();
        }
    }
}

WaitForShutdownWaitForShutdown

WaitForShutdown é disparado por meio de IHostLifetime, como ConsoleLifetime (escuta Ctrl + C/SIGINT ou SIGTERM).WaitForShutdown is triggered via the IHostLifetime, such as ConsoleLifetime (listens for Ctrl+C/SIGINT or SIGTERM). WaitForShutdown chama StopAsync.WaitForShutdown calls StopAsync.

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

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsyncWaitForShutdownAsync

WaitForShutdownAsync retorna um Task que é concluído quando o desligamento é disparado por meio do token fornecido e chama StopAsync.WaitForShutdownAsync returns a Task that completes when shutdown is triggered via the given token and calls StopAsync.

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

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

            await host.WaitForShutdownAsync();
        }

    }
}

Controle externoExternal control

O controle externo do host pode ser obtido usando os métodos que podem ser chamados externamente:External control of the host can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

WaitForStartAsync é chamado no início de StartAsync, que aguarda até que ele seja concluído antes de continuar.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. Isso pode ser usado para atrasar a inicialização até que seja sinalizado por um evento externo.This can be used to delay startup until signaled by an external event.

Interface IHostingEnvironmentIHostingEnvironment interface

IHostingEnvironment fornece informações sobre o ambiente de hospedagem do aplicativo.IHostingEnvironment provides information about the app's hosting environment. Use a injeção de construtor para obter o IHostingEnvironment para usar suas propriedades e métodos de extensão:Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class MyClass
{
    private readonly IHostingEnvironment _env;

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

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

Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core.For more information, see Usar vários ambientes no ASP.NET Core.

Interface IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime permite atividades pós-inicialização e desligamento, inclusive solicitações de desligamento normal.IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. Três propriedades na interface são tokens de cancelamento usados para registrar métodos Action que definem eventos de inicialização e desligamento.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelamentoCancellation Token Acionado quando…Triggered when…
ApplicationStarted O host foi iniciado totalmente.The host has fully started.
ApplicationStopped O host está concluindo um desligamento normal.The host is completing a graceful shutdown. Todas as solicitações devem ser processadas.All requests should be processed. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.
ApplicationStopping O host está executando um desligamento normal.The host is performing a graceful shutdown. Solicitações ainda podem estar sendo processadas.Requests may still be processing. O desligamento é bloqueado até que esse evento seja concluído.Shutdown blocks until this event completes.

O construtor injeta o serviço IApplicationLifetime em qualquer classe.Constructor-inject the IApplicationLifetime service into any class. O aplicativo de exemplo usa injeção de construtor em uma classe LifetimeEventsHostedService (uma implementação IHostedService) para registrar os eventos.The sample app uses constructor injection into a LifetimeEventsHostedService class (an IHostedService implementation) to register the events.

LifetimeEventsHostedService.cs:LifetimeEventsHostedService.cs:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

StopApplication solicita o término do aplicativo.StopApplication requests termination of the app. A classe a seguir usa StopApplication para desligar normalmente um aplicativo quando o método Shutdown da classe é chamado:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Recursos adicionaisAdditional resources