Host genérico de .NET.NET Generic Host

Por Luke LathamBy Luke Latham

Las aplicaciones ASP.NET Core configuran e inician un host.ASP.NET Core apps configure and launch a host. El host es responsable de la administración del inicio y la duración de la aplicación.The host is responsible for app startup and lifetime management.

En este artículo se describe el host genérico de .NET Core (HostBuilder).This article covers the .NET Core Generic Host (HostBuilder).

El host genérico se diferencia del host web en que desacopla la canalización HTTP de la API de host web para habilitar una mayor variedad de escenarios de host.Generic Host differs from Web Host in that it decouples the HTTP pipeline from the Web Host API to enable a wider array of host scenarios. La mensajería, las tareas en segundo plano y otras cargas de trabajo que no son de HTTP pueden usar el host genérico y beneficiarse de funcionalidades transversales, como la configuración, la inserción de dependencias (DI) y el registro.Messaging, background tasks, and other non-HTTP workloads can use Generic Host and benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

A partir de ASP.NET Core 3.0, se recomienda el host genérico para las cargas de trabajo de HTTP y las que no sean de HTTP.Starting in ASP.NET Core 3.0, Generic Host is recommended for both HTTP and non-HTTP workloads. Una implementación de servidor HTTP, si se incluye, se ejecuta como una implementación de IHostedService.An HTTP server implementation, if included, runs as an implementation of IHostedService. IHostedService es una interfaz que también se puede usar para otras cargas de trabajo.IHostedService is an interface that can be used for other workloads as well.

El host web ya no se recomienda para las aplicaciones web, pero sigue estando disponible para la compatibilidad con versiones anteriores.Web Host is no longer recommended for web apps but remains available for backward compatibility.

Nota

El resto de este artículo no se ha actualizado para la versión 3.0.This remainder of this article hasn't been updated for 3.0.

Las aplicaciones ASP.NET Core configuran e inician un host.ASP.NET Core apps configure and launch a host. El host es responsable de la administración del inicio y la duración de la aplicación.The host is responsible for app startup and lifetime management.

En este artículo se trata el host genérico de ASP.NET Core (HostBuilder), que se usa para hospedar aplicaciones que no procesan solicitudes HTTP.This article covers the ASP.NET Core Generic Host (HostBuilder), which is used for apps that don't process HTTP requests.

El objetivo del host genérico es desacoplar la canalización HTTP de la API host web para habilitar una mayor variedad de escenarios 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. La mensajería, las tareas en segundo plano y otras cargas de trabajo que no son de HTTP basadas en la ventaja de host genérico se benefician de funcionalidades transversales, como la configuración, la inserción de dependencias (DI) y el registro.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.

El host genérico es una novedad de ASP.NET Core 2.1 y no es adecuado para escenarios de hospedaje web.Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. Para escenarios de hospedaje web, use el host web.For web hosting scenarios, use the Web Host. El host genérico reemplazará al host web en una próxima versión y actuará como la API de host principal tanto en escenarios de HTTP como los que no lo son.Generic Host will replace Web Host in a future release and act as the primary host API in both HTTP and non-HTTP scenarios.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Al ejecutar la aplicación de ejemplo en Visual Studio Code, use un terminal integrado o externo.When running the sample app in Visual Studio Code, use an external or integrated terminal. No ejecute el ejemplo en internalConsole.Don't run the sample in an internalConsole.

Para establecer la consola en Visual Studio Code:To set the console in Visual Studio Code:

  1. Abra el archivo .vscode/launch.json.Open the .vscode/launch.json file.
  2. En la configuración de .NET Core Launch (console), busque la entrada console.In the .NET Core Launch (console) configuration, locate the console entry. Establezca el valor en externalTerminal o integratedTerminal.Set the value to either externalTerminal or integratedTerminal.

IntroducciónIntroduction

La biblioteca de host genérico está disponible en el espacio de nombres Microsoft.Extensions.Hosting y la proporciona el paquete Microsoft.Extensions.Hosting.The Generic Host library is available in the Microsoft.Extensions.Hosting namespace and provided by the Microsoft.Extensions.Hosting package. El paquete Microsoft.Extensions.Hosting está incluido en el metapaquete Microsoft.AspNetCore.App (ASP.NET Core 2.1 o posterior).The Microsoft.Extensions.Hosting package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

IHostedService es el punto de entrada para la ejecución de código.IHostedService is the entry point to code execution. Cada implementación de IHostedService se ejecuta en el orden de registro del servicio en ConfigureServices.Each IHostedService implementation is executed in the order of service registration in ConfigureServices. Se llama a StartAsync en cada IHostedService cuando se inicia el host, y se llama a StopAsync en orden inverso del registro cuando el host se cierra de forma estable.StartAsync is called on each IHostedService when the host starts, and StopAsync is called in reverse registration order when the host shuts down gracefully.

Configuración de un hostSet up a host

IHostBuilder es el componente principal que usan las bibliotecas y aplicaciones para inicializar, compilar y ejecutar el 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();
}

OpcionesOptions

HostOptions configura opciones para IHost.HostOptions configure options for the IHost.

Tiempo de espera de apagadoShutdown timeout

ShutdownTimeout establece el tiempo de espera para StopAsync.ShutdownTimeout sets the timeout for StopAsync. El valor predeterminado es cinco segundos.The default value is five seconds.

La siguiente configuración de opción en Program.Main aumenta el tiempo de espera de apagado predeterminado de 5 segundos a 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();

Servicios predeterminadosDefault services

Estos son los servicios que se registran durante la inicialización del host:The following services are registered during host initialization:

Configuración de hostHost configuration

La configuración del host se crea:Host configuration is created by:

Métodos de extensiónExtension methods

Clave de aplicación (nombre)Application key (name)

La propiedad IHostingEnvironment.ApplicationName se establece desde la configuración del host durante la construcción de este.The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. Para establecer el valor explícitamente, use HostDefaults.ApplicationKey:To set the value explicitly, use the HostDefaults.ApplicationKey:

Clave: nombreDeAplicaciónKey: applicationName
Tipo: cadenaType: string
Valor predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.Default: The name of the assembly containing the app's entry point.
Establecer mediante: HostBuilderContext.HostingEnvironment.ApplicationNameSet using: HostBuilderContext.HostingEnvironment.ApplicationName
Variable de entorno: <PREFIX_>APPLICATIONNAME (<PREFIX_> es opcional y definido por el usuario)Environment variable: <PREFIX_>APPLICATIONNAME (<PREFIX_> is optional and user-defined)

Raíz del contenidoContent root

Esta configuración determina la ubicación en la que el host comienza a buscar archivos de contenido.This setting determines where the host begins searching for content files.

Clave: contentRootKey: contentRoot
Tipo: cadenaType: string
Valor predeterminado: la carpeta donde se encuentra el ensamblado de la aplicación.Default: Defaults to the folder where the app assembly resides.
Establecer mediante: UseContentRootSet using: UseContentRoot
Variable de entorno: <PREFIX_>CONTENTROOT (<PREFIX_> es opcional y definido por el usuario)Environment variable: <PREFIX_>CONTENTROOT (<PREFIX_> is optional and user-defined)

Si no existe la ruta de acceso, el host no se puede iniciar.If the path doesn't exist, the host fails to start.

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

EntornoEnvironment

Establece el entorno de la aplicación.Sets the app's environment.

Clave: environmentKey: environment
Tipo: cadenaType: string
Valor predeterminado: ProducciónDefault: Production
Establecer mediante: UseEnvironmentSet using: UseEnvironment
Variable de entorno: <PREFIX_>ENVIRONMENT (<PREFIX_> es opcional y definido por el usuario)Environment variable: <PREFIX_>ENVIRONMENT (<PREFIX_> is optional and user-defined)

El entorno se puede establecer en cualquier valor.The environment can be set to any value. Los valores definidos por el marco son Development, Staging y Production.Framework-defined values include Development, Staging, and Production. Los valores no distinguen mayúsculas de minúsculas.Values aren't case sensitive.

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

ConfigureHostConfigurationConfigureHostConfiguration

ConfigureHostConfiguration usa un IConfigurationBuilder para crear una IConfiguration para el host.ConfigureHostConfiguration uses an IConfigurationBuilder to create an IConfiguration for the host. La configuración del host se usa para inicializar el IHostingEnvironment para su uso en el proceso de compilación de la aplicación.The host configuration is used to initialize the IHostingEnvironment for use in the app's build process.

Se puede llamar varias veces a ConfigureHostConfiguration con resultados de suma.ConfigureHostConfiguration can be called multiple times with additive results. El host usa cualquier opción que establezca un valor en último lugar en una clave determinada.The host uses whichever option sets a value last on a given key.

La configuración del host fluye automáticamente a la configuración de la aplicación (ConfigureAppConfiguration y al resto de la aplicación).Host configuration automatically flows to app configuration (ConfigureAppConfiguration and the rest of the app).

De forma predeterminada no se incluye ningún proveedor.No providers are included by default. Debe especificar de forma explícita los proveedores de configuración que requiere la aplicación en ConfigureHostConfiguration, así como:You must explicitly specify whatever configuration providers the app requires in ConfigureHostConfiguration, including:

  • La configuración de archivo (por ejemplo, de un archivo hostsettings.json).File configuration (for example, from a hostsettings.json file).
  • La configuración de la variable de entorno.Environment variable configuration.
  • La configuración del argumento de la línea de comandos.Command-line argument configuration.
  • Otros proveedores de configuración necesarios.Any other required configuration providers.

La configuración de archivo del host se habilita especificando la ruta base de la aplicación con SetBasePath seguido de una llamada a uno de los proveedores de configuración de archivo.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. La aplicación de ejemplo usa un archivo JSON, hostsettings.json, y llama a AddJsonFile para consumir los valores de configuración del host del archivo.The sample app uses a JSON file, hostsettings.json, and calls AddJsonFile to consume the file's host configuration settings.

Para agregar una configuración de la variable de entorno del host, llame a AddEnvironmentVariables en el generador del host.To add environment variable configuration of the host, call AddEnvironmentVariables on the host builder. AddEnvironmentVariables acepta un prefijo opcional definido por el usuario.AddEnvironmentVariables accepts an optional user-defined prefix. La aplicación de ejemplo usa el prefijo PREFIX_.The sample app uses a prefix of PREFIX_. El prefijo se quita cuando se leen las variables de entorno.The prefix is removed when the environment variables are read. Al configurar el host de la aplicación de ejemplo, el valor de la variable de entorno de PREFIX_ENVIRONMENT se convierte en el valor de configuración de host de la clave 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 el desarrollo, al usar Visual Studio o al ejecutar una aplicación con dotnet run, se pueden establecer variables de entorno en el archivo 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. En Visual Studio Code, las variables de entorno se pueden establecer en el archivo .vscode/launch.json durante el desarrollo.In Visual Studio Code, environment variables may be set in the .vscode/launch.json file during development. Para obtener más información, vea Usar varios entornos en ASP.NET Core.For more information, see Usar varios entornos en ASP.NET Core.

La configuración de la línea de comandos se agrega llamando a AddCommandLine.Command-line configuration is added by calling AddCommandLine. La configuración de la línea de comandos se agrega en último lugar para permitir que los argumentos de la línea de comandos invaliden la configuración proporcionada por los proveedores de configuración 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"
}

Se puede proporcionar una configuración adicional con las claves applicationName y contentRoot.Additional configuration can be provided with the applicationName and contentRoot keys.

Configuración de HostBuilder de ejemplo con 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

La configuración de la aplicación se crea llamando a ConfigureAppConfiguration en la implementación de IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on the IHostBuilder implementation. ConfigureAppConfiguration usa un IConfigurationBuilder para crear una IConfiguration para la aplicación.ConfigureAppConfiguration uses an IConfigurationBuilder to create an IConfiguration for the app. Se puede llamar varias veces a ConfigureAppConfiguration con resultados de suma.ConfigureAppConfiguration can be called multiple times with additive results. La aplicación usa cualquier opción que establezca un valor en último lugar en una clave determinada.The app uses whichever option sets a value last on a given key. La configuración creada por ConfigureAppConfiguration está disponible en HostBuilderContext.Configuration para las operaciones posteriores y en Services.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and in Services.

La configuración de la aplicación recibe automáticamente la configuración del host proporcionada por ConfigureHostConfiguration.App configuration automatically receives host configuration provided by ConfigureHostConfiguration.

Configuración de aplicación de ejemplo con 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 los archivos de configuración al directorio de salida, especifique los archivos de configuración como elementos de proyecto de MSBuild en el archivo de proyecto.To move settings files to the output directory, specify the settings files as MSBuild project items in the project file. La aplicación de ejemplo mueve sus archivos de configuración de aplicación JSON y hostsettings.json con el elemento <Content> siguiente: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>

Nota

Los métodos de extensión de configuración, como AddJsonFile y AddEnvironmentVariables requieren paquetes NuGet adicionales, como Microsoft.Extensions.Configuration.Json y 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 la aplicación use el metapaquete Microsoft.AspNetCore.App, además del paquete principal Microsoft.Extensions.Configuration, se deben agregar estos paquetes.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 obtener más información, vea Configuración en ASP.NET Core.For more information, see Configuración en ASP.NET Core.

ConfigureServicesConfigureServices

ConfigureServices agrega los servicios al contenedor de inserción de dependencias de la aplicación.ConfigureServices adds services to the app's dependency injection container. Se puede llamar varias veces a ConfigureServices con resultados de suma.ConfigureServices can be called multiple times with additive results.

Un servicio hospedado es una clase con lógica de tarea en segundo plano que implementa la interfaz IHostedService.A hosted service is a class with background task logic that implements the IHostedService interface. Para obtener más información, vea Tareas en segundo plano con servicios hospedados en ASP.NET Core.For more information, see Tareas en segundo plano con servicios hospedados en ASP.NET Core.

La aplicación de ejemplo usa el método de extensión AddHostedService para agregar un servicio para eventos de duración, LifetimeEventsHostedService, y una tarea en segundo plano programada, TimedHostedService, a la aplicación: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 agrega un delegado para configurar el ILoggingBuilder proporcionado.ConfigureLogging adds a delegate for configuring the provided ILoggingBuilder. Se puede llamar varias veces a ConfigureLogging con resultados de suma.ConfigureLogging may be called multiple times with additive results.

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

UseConsoleLifetimeUseConsoleLifetime

UseConsoleLifetime escucha Ctrl+C/SIGINT o SIGTERM y llama a StopApplication para iniciar el proceso de cierre.UseConsoleLifetime listens for Ctrl+C/SIGINT or SIGTERM and calls StopApplication to start the shutdown process. UseConsoleLifetime desbloquea extensiones como RunAsync y WaitForShutdownAsync.UseConsoleLifetime unblocks extensions such as RunAsync and WaitForShutdownAsync. ConsoleLifetime ya está registrado previamente como la implementación de duración predeterminada.ConsoleLifetime is pre-registered as the default lifetime implementation. Se usa la última duración registrada.The last lifetime registered is used.

var host = new HostBuilder()
    .UseConsoleLifetime()

Configuración del contenedorContainer configuration

Para permitir la conexión a otros contenedores, el host puede aceptar IServiceProviderFactory<TContainerBuilder>.To support plugging in other containers, the host can accept an IServiceProviderFactory<TContainerBuilder>. Proporcionar un generador no forma parte del registro de contenedor DI, sino que es un host intrínseco utilizado para crear el contenedor DI determinado.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>) invalida el generador predeterminado utilizado para crear el proveedor de servicios de la aplicación.UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to create the app's service provider.

La configuración personalizada del contenedor está administrada por el método ConfigureContainer.Custom container configuration is managed by the ConfigureContainer method. ConfigureContainer proporciona una experiencia fuertemente tipada para configurar el contenedor sobre la API de host subyacente.ConfigureContainer provides a strongly-typed experience for configuring the container on top of the underlying host API. Se puede llamar varias veces a ConfigureContainer con resultados de suma.ConfigureContainer can be called multiple times with additive results.

Crear un contenedor de servicios de la aplicación:Create a service container for the app:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Proporcionar un generador de contenedor de servicio: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();
        }
    }
}

Usar el generador y configurar el contenedor de servicio personalizado de la aplicación:Use the factory and configure the custom service container for the app:

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

ExtensibilidadExtensibility

La extensibilidad de host se realiza con métodos de extensión en IHostBuilder.Host extensibility is performed with extension methods on IHostBuilder. En el ejemplo siguiente se muestra cómo un método de extensión extiende una implementación de IHostBuilder con el ejemplo TimedHostedService demostrado en Tareas en segundo plano con servicios hospedados en ASP.NET Core.The following example shows how an extension method extends an IHostBuilder implementation with the TimedHostedService example demonstrated in Tareas en segundo plano con servicios hospedados en ASP.NET Core.

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

await host.StartAsync();

Una aplicación establece el método de extensión UseHostedService para registrar el servicio hospedado pasado en 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>());
    }
}

Administración del hostManage the host

La implementación de IHost es la responsable de iniciar y detener las implementaciones de IHostedService que están registradas en el contenedor de servicios.The IHost implementation is responsible for starting and stopping the IHostedService implementations that are registered in the service container.

RunRun

Run inicia la aplicación y bloquea el subproceso que realiza la llamada hasta que se cierre el host: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 inicia la aplicación y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre: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 la compatibilidad de la consola, compila e inicia el host y espera a que se cierre Ctrl+C/SIGINT o SIGTERM.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 y StopAsyncStart and StopAsync

Start inicia el host de forma sincrónica.Start starts the host synchronously.

StopAsync intenta detener el host en el tiempo de espera proporcionado.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 y StopAsyncStartAsync and StopAsync

StartAsync inicia la aplicación.StartAsync starts the app.

StopAsync detiene la aplicación.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 se desencadena mediante IHostLifetime, como ConsoleLifetime (escucha Ctrl+C/SIGINT o SIGTERM).WaitForShutdown is triggered via the IHostLifetime, such as ConsoleLifetime (listens for Ctrl+C/SIGINT or SIGTERM). WaitForShutdown llama a 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 devuelve Task, que se completa cuando se desencadena el cierre a través del token determinado y llama a 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();
        }

    }
}

Control externoExternal control

El control externo del host se puede lograr mediante métodos a los que se pueda llamar de forma externa: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 se llama al inicio de StartAsync, que espera hasta que se complete antes de continuar.WaitForStartAsync is called at the start of StartAsync, which waits until it's complete before continuing. Esto se puede usar para retrasar el inicio hasta que lo indique un evento externo.This can be used to delay startup until signaled by an external event.

Interfaz IHostingEnvironmentIHostingEnvironment interface

IHostingEnvironment proporciona información sobre el entorno de hospedaje de la aplicación.IHostingEnvironment provides information about the app's hosting environment. Use inserción de constructores para obtener IHostingEnvironment a fin de utilizar sus propiedades y métodos de extensión: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 obtener más información, vea Usar varios entornos en ASP.NET Core.For more information, see Usar varios entornos en ASP.NET Core.

Interfaz IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime permite actividades posteriores al inicio y cierre, incluidas las solicitudes de cierre estable.IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. Hay tres propiedades en la interfaz que son tokens de cancelación usados para registrar métodos Action que definen los eventos de inicio y apagado.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelaciónCancellation Token Se desencadena cuando…Triggered when…
ApplicationStarted El host se ha iniciado completamente.The host has fully started.
ApplicationStopped El host está completando un apagado estable.The host is completing a graceful shutdown. Deben procesarse todas las solicitudes.All requests should be processed. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.
ApplicationStopping El host está realizando un apagado estable.The host is performing a graceful shutdown. Puede que todavía se estén procesando las solicitudes.Requests may still be processing. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.

Inserción de constructor del servicio IApplicationLifetime en cualquier clase.Constructor-inject the IApplicationLifetime service into any class. En la aplicación de ejemplo se usa la inserción de constructor en una clase LifetimeEventsHostedService (una implementación de IHostedService) para registrar los 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 la terminación de la aplicación.StopApplication requests termination of the app. La siguiente clase usa StopApplication para cerrar de forma estable una aplicación cuando se llama al método Shutdown de esa clase: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 adicionalesAdditional resources