Host genérico de .NET.NET Generic Host

En este artículo se presenta el host genérico .NET Core (HostBuilder) y se proporciona orientación sobre cómo usarlo.This article introduces the .NET Core Generic Host (HostBuilder) and provides guidance on how to use it.

¿Qué es un host?What's a host?

El host es un objeto que encapsula todos los recursos de la aplicación, como:A host is an object that encapsulates an app's resources, such as:

  • Inserción de dependencias (ID)Dependency injection (DI)
  • RegistroLogging
  • ConfiguraciónConfiguration
  • Implementaciones de IHostedServiceIHostedService implementations

Cuando se inicia un host, llama a IHostedService.StartAsync en cada implementación de IHostedService que encuentra en el contenedor de ID.When a host starts, it calls IHostedService.StartAsync on each implementation of IHostedService that it finds in the DI container. En una aplicación web, una de las implementaciones de IHostedService es un servicio web que inicia una implementación de servidor HTTP.In a web app, one of the IHostedService implementations is a web service that starts an HTTP server implementation.

La razón principal para incluir todos los recursos interdependientes de la aplicación en un objeto es la administración de la duración: el control sobre el inicio de la aplicación y el apagado estable.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.

En las versiones de ASP.NET Core anteriores a la 3.0, el host web se usa para cargas de trabajo HTTP.In versions of ASP.NET Core earlier than 3.0, the Web Host is used for HTTP workloads. El host web ya no se recomienda para las aplicaciones web, pero sigue estando disponible para la compatibilidad con versiones anteriores.The Web Host is no longer recommended for web apps and remains available only for backward compatibility.

Configuración de un hostSet up a host

Normalmente se configura, compila y ejecuta el host por el código de la clase Program.The host is typically configured, built, and run by code in the Program class. El método Main realiza las acciones siguientes:The Main method:

  • Llama a un método CreateHostBuilder para crear y configurar un objeto del generador.Calls a CreateHostBuilder method to create and configure a builder object.
  • Llama a los métodos Build y Run en el objeto del generador.Calls Build and Run methods on the builder object.

Este es el código de Program.cs para una carga de trabajo no HTTP, con una sola implementación de IHostedService agregada para el contenedor de ID.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 una carga de trabajo HTTP, el método Main es el mismo, pero CreateHostBuilder llama a 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>();
        });

Si la aplicación usa Entity Framework Core, no cambie el nombre o la firma del método CreateHostBuilder.If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method. Las herramientas de Entity Framework Core esperan encontrar un método CreateHostBuilder que configure el host sin ejecutar la aplicación.The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without running the app. Para obtener más información, consulte Creación de DbContext en tiempo de diseño.For more information, see Design-time DbContext Creation.

Configuración predeterminada del generadorDefault builder settings

El método CreateDefaultBuilder realiza las acciones siguientes:The CreateDefaultBuilder method:

  • Establece la raíz de contenido en la ruta de acceso devuelta por GetCurrentDirectory.Sets the content root to the path returned by GetCurrentDirectory.
  • Carga la configuración de host de:Loads host configuration from:
    • Variables de entorno con el prefijo "DOTNET_".Environment variables prefixed with "DOTNET_".
    • Argumentos de la línea de comandos.Command-line arguments.
  • Carga la configuración de aplicación de:Loads app configuration from:
    • appsettings.json.appsettings.json.
    • appsettings.{Environment}.json.appsettings.{Environment}.json.
    • Administrador de secretos, cuando la aplicación se ejecuta en el entorno Development.Secret Manager when the app runs in the Development environment.
    • Variables de entorno.Environment variables.
    • Argumentos de la línea de comandos.Command-line arguments.
  • Agrega los siguientes proveedores de registro:Adds the following logging providers:
    • ConsolaConsole
    • DepuraciónDebug
    • EventSourceEventSource
    • EventLog (solo si se ejecuta en Windows)EventLog (only when running on Windows)
  • Permite la validación del ámbito y la validación de dependencias si el entorno es Desarrollo.Enables scope validation and dependency validation when the environment is Development.

El método ConfigureWebHostDefaults realiza las acciones siguientes:The ConfigureWebHostDefaults method:

En las secciones Configuración para todos los tipos de aplicaciones y Configuración para las aplicaciones web, más adelante en este artículo, se muestra cómo invalidar la configuración predeterminada del generador.The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

Servicios proporcionados por el marco de trabajoFramework-provided services

Los servicios que se registran automáticamente incluyen los siguientes:Services that are registered automatically include the following:

Para obtener una lista de todos los servicios proporcionados por la plataforma de trabajo, consulte Inserción de dependencias en ASP.NET Core.For a list of all framework-provided services, see Inserción de dependencias en ASP.NET Core.

IHostApplicationLifetimeIHostApplicationLifetime

Permite insertar el servicio IHostApplicationLifetime (anteriormente, IApplicationLifetime) en cualquier clase para controlar las tareas posteriores al inicio y el cierre estable.Inject the IHostApplicationLifetime (formerly IApplicationLifetime) service into any class to handle post-startup and graceful shutdown tasks. Tres de las propiedades de la interfaz son tokens de cancelación que se usan para registrar los métodos del controlador de eventos de inicio y detención de las aplicaciones.Three properties on the interface are cancellation tokens used to register app start and app stop event handler methods. La interfaz también incluye un método StopApplication.The interface also includes a StopApplication method.

El ejemplo siguiente es una implementación de IHostedService que registra los 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

La implementación de IHostLifetime controla cuándo se inicia el host y cuándo se detiene.The IHostLifetime implementation controls when the host starts and when it stops. Se usa la última implementación registrada.The last implementation registered is used.

ConsoleLifetime es la implementación predeterminada de IHostLifetime.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:ConsoleLifetime:

IHostEnvironmentIHostEnvironment

Permite insertar el servicio IHostEnvironment en una clase para obtener información sobre lo siguiente:Inject the IHostEnvironment service into a class to get information about the following:

Las aplicaciones web implementan la interfaz de IWebHostEnvironment, que hereda IHostEnvironment y agrega:Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds:

Configuración de hostHost configuration

La configuración de host se usa para las propiedades de la implementación de IHostEnvironment.Host configuration is used for the properties of the IHostEnvironment implementation.

La configuración de host está disponible en HostBuilderContext.Configuration, en ConfigureAppConfiguration.Host configuration is available from HostBuilderContext.Configuration inside ConfigureAppConfiguration. Después de ConfigureAppConfiguration, HostBuilderContext.Configuration se reemplaza por la configuración de la aplicación.After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

Para agregar la configuración de host, llame a ConfigureHostConfiguration en IHostBuilder.To add host configuration, call ConfigureHostConfiguration on IHostBuilder. 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.

El proveedor de variables de entorno con el prefijo DOTNET_ y los argumentos de línea de comandos se incluyen mediante CreateDefaultBuilder.The environment variable provider with prefix DOTNET_ and command line args are included by CreateDefaultBuilder. Para las aplicaciones web, se agrega el proveedor de variables de entorno con el prefijo ASPNETCORE_.For web apps, the environment variable provider with prefix ASPNETCORE_ is added. El prefijo se quita cuando se leen las variables de entorno.The prefix is removed when the environment variables are read. Por ejemplo, el valor de la variable de entorno de ASPNETCORE_ENVIRONMENT se convierte en el valor de configuración de host de la clave environment.For example, the environment variable value for ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

En el ejemplo siguiente se crea la configuración 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);
    });

Configuración de aplicacionesApp configuration

La configuración de la aplicación se crea llamando a ConfigureAppConfiguration en IHostBuilder.App configuration is created by calling ConfigureAppConfiguration on IHostBuilder. 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 como servicio de ID.The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and as a service from DI. La configuración de host también se agrega a la configuración de la aplicación.The host configuration is also added to the app configuration.

Para más información, consulte Configuración en ASP.NET Core.For more information, see Configuration in ASP.NET Core.

Configuración para todos los tipos de aplicacionesSettings for all app types

En esta sección se enumeran las configuraciones de host que se aplican a las cargas de trabajo HTTP y no HTTP.This section lists host settings that apply to both HTTP and non-HTTP workloads. De forma predeterminada, las variables de entorno que se usan para configurar estas opciones pueden tener un prefijo DOTNET_ o ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

ApplicationNameApplicationName

La propiedad IHostEnvironment.ApplicationName se establece desde la configuración de host durante la construcción de este.The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

Clave: nombreDeAplicaciónKey: applicationName
Tipo: cadenaType: string
Predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.Default: The name of the assembly that contains the app's entry point. Variable de entorno: <PREFIX_>APPLICATIONNAMEEnvironment variable: <PREFIX_>APPLICATIONNAME

Para establecer este valor, use la variable de entorno.To set this value, use the environment variable.

ContentRootPathContentRootPath

La propiedad IHostEnvironment.ContentRootPath determina la ubicación en la que el host comienza a buscar archivos de contenido.The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. Si no existe la ruta de acceso, el host no se puede iniciar.If the path doesn't exist, the host fails to start.

Clave: contentRootKey: contentRoot
Tipo: cadenaType: string
Predeterminado: carpeta donde se encuentra el ensamblado de la aplicación.Default: The folder where the app assembly resides.
Variable de entorno: <PREFIX_>CONTENTROOTEnvironment variable: <PREFIX_>CONTENTROOT

Para establecer este valor, use la variable de entorno o llame a UseContentRoot en IHostBuilder:To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

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

EnvironmentNameEnvironmentName

La propiedad IHostEnvironment.EnvironmentName puede establecerse en cualquier valor.The IHostEnvironment.EnvironmentName property 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.

Clave: environmentKey: environment
Tipo: cadenaType: string
Valor predeterminado: ProducciónDefault: Production
Variable de entorno: <PREFIX_>ENVIRONMENTEnvironment variable: <PREFIX_>ENVIRONMENT

Para establecer este valor, use la variable de entorno o llame a UseEnvironment en IHostBuilder:To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

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

ShutdownTimeoutShutdownTimeout

HostOptions.ShutdownTimeout establece el tiempo de espera para StopAsync.HostOptions.ShutdownTimeout sets the timeout for StopAsync. El valor predeterminado es cinco segundos.The default value is five seconds. Durante el período de tiempo de espera, el host:During the timeout period, the host:

Si el período de tiempo de espera expira antes de que todos los servicios hospedados se hayan detenido, los servicios activos que queden se detendrán cuando se cierre la aplicación.If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. Los servicios se detienen aun cuando no hayan terminado de procesarse.The services stop even if they haven't finished processing. Si los servicios requieren más tiempo para detenerse, aumente el valor de tiempo de espera.If services require additional time to stop, increase the timeout.

Clave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Predeterminado: 5 segundos Variable de entorno: <PREFIX_>SHUTDOWNTIMEOUTSECONDSDefault: 5 seconds Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

Para establecer este valor, use la variable de entorno o configure HostOptions.To set this value, use the environment variable or configure HostOptions. El siguiente ejemplo establece el tiempo de espera en 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);
        });
    });

Configuración para las aplicaciones webSettings for web apps

Algunas configuraciones de host solo se aplican a las cargas de trabajo HTTP.Some host settings apply only to HTTP workloads. De forma predeterminada, las variables de entorno que se usan para configurar estas opciones pueden tener un prefijo DOTNET_ o ASPNETCORE_.By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

Los métodos de extensión en IWebHostBuilder están disponibles para estas configuraciones.Extension methods on IWebHostBuilder are available for these settings. Los ejemplos de código que muestran cómo llamar a los métodos de extensión suponen que webBuilder es una instancia de IWebHostBuilder, como en el ejemplo siguiente: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

Cuando es false, los errores durante el inicio provocan la salida del host.When false, errors during startup result in the host exiting. Cuando es true, el host captura las excepciones producidas durante el inicio e intenta iniciar el servidor.When true, the host captures exceptions during startup and attempts to start the server.

Clave: captureStartupErrorsKey: captureStartupErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: false, a menos que la aplicación se ejecute con Kestrel detrás de IIS, en cuyo caso el valor predeterminado es true.Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Variable de entorno: <PREFIX_>CAPTURESTARTUPERRORSEnvironment variable: <PREFIX_>CAPTURESTARTUPERRORS

Para establecer este valor, utilice la configuración o llame a CaptureStartupErrors:To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrorsDetailedErrors

Si se habilita, o si el entorno es Development, la aplicación captura errores detallados.When enabled, or when the environment is Development, the app captures detailed errors.

Clave: detailedErrorsKey: detailedErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: falseDefault: false
Variable de entorno: <PREFIX_>_DETAILEDERRORSEnvironment variable: <PREFIX_>_DETAILEDERRORS

Para establecer este valor, utilice la configuración o llame a UseSetting:To set this value, use configuration or call UseSetting:

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

HostingStartupAssembliesHostingStartupAssemblies

Una cadena delimitada por punto y coma de ensamblados de inicio de hospedaje para cargar en el inicio.A semicolon-delimited string of hosting startup assemblies to load on startup. Aunque el valor de configuración predeterminado es una cadena vacía, los ensamblados de inicio de hospedaje incluyen siempre el ensamblado de la aplicación.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. Cuando se especifican los ensamblados de inicio de hospedaje, estos se agregan al ensamblado de la aplicación para que se carguen cuando la aplicación genera sus servicios comunes durante el inicio.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.

Clave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: cadenaType: string
Valor predeterminado: Cadena vacíaDefault: Empty string
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:To set this value, use configuration or call UseSetting:

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

HostingStartupExcludeAssembliesHostingStartupExcludeAssemblies

Una cadena delimitada por punto y coma de ensamblados de inicio de hospedaje para excluir en el inicio.A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Clave: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Tipo: cadenaType: string
Valor predeterminado: Cadena vacíaDefault: Empty string
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:To set this value, use configuration or call UseSetting:

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

HTTPS_PortHTTPS_Port

Puerto de redireccionamiento HTTPS.The HTTPS redirect port. Se usa en Exigir HTTPS.Used in enforcing HTTPS.

Clave: https_port Tipo: cadena Valor predeterminado: no se ha establecido ningún valor predeterminado.Key: https_port Type: string Default: A default value isn't set. Variable de entorno: <PREFIX_>HTTPS_PORTEnvironment variable: <PREFIX_>HTTPS_PORT

Para establecer este valor, utilice la configuración o llame a UseSetting:To set this value, use configuration or call UseSetting:

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

PreferHostingUrlsPreferHostingUrls

Indica si el host debe escuchar en las direcciones URL configuradas con IWebHostBuilder en lugar de las que estén configuradas con la implementación de IServer.Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those configured with the IServer implementation.

Clave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: trueDefault: true
Variable de entorno: <PREFIX_>_PREFERHOSTINGURLSEnvironment variable: <PREFIX_>_PREFERHOSTINGURLS

Para establecer este valor, use la variable de entorno o llame a PreferHostingUrls:To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartupPreventHostingStartup

Impide la carga automática de los ensamblados de inicio de hospedaje, incluidos los configurados por el ensamblado de la aplicación.Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. Para más información, consulte Uso de ensamblados de inicio de hospedaje en ASP.NET Core.For more information, see Uso de ensamblados de inicio de hospedaje en ASP.NET Core.

Clave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: falseDefault: false
Variable de entorno: <PREFIX_>_PREVENTHOSTINGSTARTUPEnvironment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

Para establecer este valor, use la variable de entorno o llame a UseSetting:To set this value, use the environment variable or call UseSetting :

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

StartupAssemblyStartupAssembly

Ensamblado en el que se va a buscar la clase Startup.The assembly to search for the Startup class.

Clave: startupAssembly Tipo: cadenaKey: startupAssembly Type: string
Predeterminado: el ensamblado de la aplicaciónDefault: The app's assembly
Variable de entorno: <PREFIX_>STARTUPASSEMBLYEnvironment variable: <PREFIX_>STARTUPASSEMBLY

Para establecer este valor, use la variable de entorno o llame a UseStartup.To set this value, use the environment variable or call UseStartup. UseStartup puede tomar un nombre del ensamblado (string) o un tipo (TStartup).UseStartup can take an assembly name (string) or a type (TStartup). Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.If multiple UseStartup methods are called, the last one takes precedence.

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

Direcciones URLURLs

Lista delimitada por punto y coma de las direcciones IP o las direcciones de host con los puertos y protocolos en los que el servidor debe escuchar las solicitudes.A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should listen on for requests. Por ejemplo: http://localhost:123.For example, http://localhost:123. Use "*" para indicar que el servidor debe escuchar las solicitudes en cualquier dirección IP o nombre de host con el puerto y el protocolo especificados (por ejemplo, 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). El protocolo (http:// o https://) debe incluirse con cada dirección URL.The protocol (http:// or https://) must be included with each URL. Los formatos admitidos varían de un servidor a otro.Supported formats vary among servers.

Clave: urlsKey: urls
Tipo: cadenaType: string
Valor predeterminado: http://localhost:5000 y https://localhost:5001 Variable de entorno: <PREFIX_>URLSDefault: http://localhost:5000 and https://localhost:5001 Environment variable: <PREFIX_>URLS

Para establecer este valor, use la variable de entorno o llame a UseUrls:To set this value, use the environment variable or call UseUrls:

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

Kestrel tiene su propia API de configuración de punto de conexión.Kestrel has its own endpoint configuration API. Para más información, consulte Implementación del servidor web Kestrel en ASP.NET Core.For more information, see Implementación del servidor web Kestrel en ASP.NET Core.

WebRootWebRoot

Ruta de acceso relativa a los recursos estáticos de la aplicación.The relative path to the app's static assets.

Clave: webrootKey: webroot
Tipo: cadenaType: string
Predeterminado: (Raíz de contenido)/wwwroot, si existe la ruta de acceso.Default: (Content Root)/wwwroot, if the path exists. Si la ruta de acceso no existe, se utiliza un proveedor de archivos no-op.If the path doesn't exist, a no-op file provider is used.
Variable de entorno: <PREFIX_>WEBROOTEnvironment variable: <PREFIX_>WEBROOT

Para establecer este valor, use la variable de entorno o llame a UseWebRoot:To set this value, use the environment variable or call UseWebRoot:

webBuilder.UseWebRoot("public");

Administración de la vigencia del hostManage the host lifetime

Llame a los métodos en la implementación de IHost creada para iniciar y detener la aplicación.Call methods on the built IHost implementation to start and stop the app. Estos métodos afectan a todas las implementaciones de IHostedService registradas en el contenedor de servicios.These methods affect all 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.

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.

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.

IniciarStart

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

StartAsyncStartAsync

StartAsync inicia el host y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre.StartAsync starts the host and returns a Task that completes when the cancellation token or shutdown is triggered.

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.

StopAsyncStopAsync

StopAsync intenta detener el host en el tiempo de espera proporcionado.StopAsync attempts to stop the host within the provided timeout.

WaitForShutdownWaitForShutdown

WaitForShutdown bloquea el subproceso de llamada hasta que IHostLifetime desencadena el cierre, por ejemplo, a través de Ctrl+C/SIGINT o SIGTERM.WaitForShutdown blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via Ctrl+C/SIGINT or SIGTERM.

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.

Control externoExternal control

El control directo de la vigencia del host se puede lograr mediante métodos a los que se puede llamar de forma externa: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));
        }
    }
}

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.

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 más información, consulte 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 más información, consulte 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 más información, consulte 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 más información, consulte 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