Host genérico de .NET en ASP.NET Core

Artículo
09/21/2021
19 minutos para leer

Las plantillas de ASP.NET Core crean un host genérico de .NET Core (HostBuilder).

En este tema se proporciona información sobre cómo usar el host genérico de ASP.NET Core. Para obtener información sobre cómo usar un host genérico de .NET en aplicaciones de consola, consulte Host genérico de .NET.

Definición de host

El host es un objeto que encapsula todos los recursos de la aplicación, como:

Inserción de dependencias (ID)
Registro
Configuración
Implementaciones de IHostedService

Cuando se inicia un host, llama a IHostedService.StartAsync en cada implementación de IHostedService registrada en la colección de servicios hospedados del contenedor de servicios. En una aplicación web, una de las implementaciones de IHostedService es un servicio web que inicia una implementación de servidor HTTP.

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.

Configuración de un host

Normalmente se configura, compila y ejecuta el host por el código de la clase Program. El método Main realiza las acciones siguientes:

Llama a un método CreateHostBuilder para crear y configurar un objeto del generador.
Llama a los métodos Build y Run en el objeto del generador.

Las plantillas web de ASP.NET Core generan el código siguiente para crear un host:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

En el código siguiente se crea una carga de trabajo que no es HTTP con una implementación de IHostedService agregada al contenedor de DI.

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

Para una carga de trabajo HTTP, el método Main es el mismo, pero CreateHostBuilder llama a 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. Las herramientas de Entity Framework Core esperan encontrar un método CreateHostBuilder que configure el host sin ejecutar la aplicación. Para obtener más información, consulte Creación de DbContext en tiempo de diseño.

Configuración predeterminada del generador

El método CreateDefaultBuilder realiza las acciones siguientes:

Establece la raíz de contenido en la ruta de acceso devuelta por GetCurrentDirectory.
Carga la configuración de host de:
- Variables de entorno con el prefijo DOTNET_.
- Argumentos de la línea de comandos.
Carga la configuración de aplicación de:
- appsettings.json.
- appsettings.{Environment}.json.
- Secretos del usuario cuando la aplicación se ejecuta en el entorno Development.
- Variables de entorno.
- Argumentos de la línea de comandos.
Agrega los siguientes proveedores de registro:
- Consola
- Depuración
- EventSource
- EventLog (solo si se ejecuta en Windows)
Permite la validación del ámbito y la validación de dependencias si el entorno es Desarrollo.

El método ConfigureWebHostDefaults realiza las acciones siguientes:

Carga la configuración de host desde las variables de entorno con el prefijo ASPNETCORE_.
Establece el servidor Kestrel como servidor web y lo configura por medio de los proveedores de configuración de hospedaje de la aplicación. Para conocer las opciones predeterminadas del servidor Kestrel, consulte Configuración de opciones para el servidor web Kestrel de ASP.NET Core.
Agrega el middleware de filtrado de hosts.
Agrega middleware de encabezados reenviados si ASPNETCORE_FORWARDEDHEADERS_ENABLED es igual a true.
Permite la integración de IIS. Para consultar las opciones predeterminadas de IIS, vea Hospedaje de ASP.NET Core en Windows con IIS.

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.

Servicios proporcionados por el marco de trabajo

Los servicios siguientes se registran de forma automática:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment/IWebHostEnvironment

Para más información sobre los servicios proporcionados por el marco, consulte Inserción de dependencias en ASP.NET Core.

IHostApplicationLifetime

Permite insertar el servicio IHostApplicationLifetime (anteriormente, IApplicationLifetime) en cualquier clase para controlar las tareas posteriores al inicio y el cierre estable. 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. La interfaz también incluye un método StopApplication.

El ejemplo siguiente es una implementación de IHostedService que registra los eventos IHostApplicationLifetime:

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

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

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

        return Task.CompletedTask;
    }

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

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

        // Perform post-startup activities here
    }

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

        // Perform on-stopping activities here
    }

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

        // Perform post-stopped activities here
    }
}

IHostLifetime

La implementación de IHostLifetime controla cuándo se inicia el host y cuándo se detiene. Se usa la última implementación registrada.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime es la implementación predeterminada de IHostLifetime. ConsoleLifetime:

escucha Ctrl+C/SIGINT o SIGTERM, y llama a StopApplication para iniciar el proceso de apagado.
Desbloquea extensiones como RunAsync y WaitForShutdownAsync.

IHostEnvironment

Permite insertar el servicio IHostEnvironment en una clase para obtener información sobre los valores siguientes:

ApplicationName
EnvironmentName
ContentRootPath

Las aplicaciones web implementan la interfaz IWebHostEnvironment, que hereda IHostEnvironment y agrega WebRootPath.

Configuración de host

La configuración de host se usa para las propiedades de la implementación de IHostEnvironment.

La configuración de host está disponible en HostBuilderContext.Configuration, en ConfigureAppConfiguration. Después de ConfigureAppConfiguration, HostBuilderContext.Configuration se reemplaza por la configuración de la aplicación.

Para agregar la configuración de host, llame a ConfigureHostConfiguration en IHostBuilder. Se puede llamar varias veces a ConfigureHostConfiguration con resultados de suma. El host usa cualquier opción que establezca un valor en último lugar en una clave determinada.

El proveedor de variables de entorno con el prefijo DOTNET_ y los argumentos de línea de comandos se incluyen mediante CreateDefaultBuilder. Para las aplicaciones web, se agrega el proveedor de variables de entorno con el prefijo ASPNETCORE_. El prefijo se quita cuando se leen las variables de entorno. 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.

En el ejemplo siguiente se crea la configuración de host:

// using Microsoft.Extensions.Configuration;

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

Configuración de aplicaciones

La configuración de la aplicación se crea llamando a ConfigureAppConfiguration en IHostBuilder. Se puede llamar varias veces a ConfigureAppConfiguration con resultados de suma. La aplicación usa cualquier opción que establezca un valor en último lugar en una clave determinada.

La configuración creada por ConfigureAppConfiguration está disponible en HostBuilderContext.Configuration para las operaciones posteriores y como servicio de ID. La configuración de host también se agrega a la configuración de la aplicación.

Para más información, consulte Configuración en ASP.NET Core.

Configuración para todos los tipos de aplicaciones

En esta sección se enumeran las configuraciones de host que se aplican a las cargas de trabajo HTTP y no HTTP. De forma predeterminada, las variables de entorno que se usan para configurar estas opciones pueden tener un prefijo DOTNET_ o ASPNETCORE_. Para más información, consulte Configuración predeterminada del generador.

ApplicationName

La propiedad IHostEnvironment.ApplicationName se establece desde la configuración de host durante la construcción de este.

Clave: applicationName
Tipo: string
Predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.
Variable de entorno: <PREFIX_>APPLICATIONNAME

Para establecer este valor, use la variable de entorno.

ContentRoot

La propiedad IHostEnvironment.ContentRootPath determina la ubicación en la que el host comienza a buscar archivos de contenido. Si no existe la ruta de acceso, el host no se puede iniciar.

Clave: contentRoot
Tipo: string
Predeterminado: carpeta donde se encuentra el ensamblado de la aplicación.
Variable de entorno: <PREFIX_>CONTENTROOT

Para establecer este valor, use la variable de entorno o llame a UseContentRoot en IHostBuilder:

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

Para obtener más información, consulte:

EnvironmentName

La propiedad IHostEnvironment.EnvironmentName puede establecerse en cualquier valor. Los valores definidos por el marco son Development, Staging y Production. Los valores no distinguen mayúsculas de minúsculas.

Clave: environment
Tipo: string
Predeterminado: Production
Variable de entorno: <PREFIX_>ENVIRONMENT

Para establecer este valor, use la variable de entorno o llame a UseEnvironment en IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout establece el tiempo de espera para StopAsync. El valor predeterminado es cinco segundos. Durante el período de tiempo de espera, el host:

Activa IHostApplicationLifetime.ApplicationStopping.
Trata de detener los servicios hospedados y registra los errores que se producen en los servicios que no se puedan detener.

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. Los servicios se detienen aun cuando no hayan terminado de procesarse. Si los servicios requieren más tiempo para detenerse, aumente el valor de tiempo de espera.

Clave: shutdownTimeoutSeconds
Tipo: int
Predeterminado: 5 segundos
Variable de entorno: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

Para establecer este valor, use la variable de entorno o configure HostOptions. El siguiente ejemplo establece el tiempo de espera en 20 segundos:

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

Deshabilitación de la recarga de configuración de aplicaciones al realizar un cambio

De forma predeterminada, appsettings.json y appsettings.{Environment}.json se recargan cuando cambia el archivo. Para deshabilitar este comportamiento de recarga en ASP.NET Core 5.0 o versiones posteriores, establezca la clave hostBuilder:reloadConfigOnChange en false.

Clave: hostBuilder:reloadConfigOnChange
Tipo: bool (true o 1)
Predeterminado: true
Argumento de la línea de comandos: hostBuilder:reloadConfigOnChange
Variable de entorno: <PREFIX_>hostBuilder:reloadConfigOnChange

Advertencia

El separador de dos puntos (:) no funciona con las claves jerárquicas de variables de entorno en todas las plataformas. Para más información, consulte Variables de entorno.

Configuración para las aplicaciones web

Algunas configuraciones de host solo se aplican a las cargas de trabajo HTTP. De forma predeterminada, las variables de entorno que se usan para configurar estas opciones pueden tener un prefijo DOTNET_ o ASPNETCORE_.

Los métodos de extensión en IWebHostBuilder están disponibles para estas configuraciones. 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:

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

CaptureStartupErrors

Cuando es false, los errores durante el inicio provocan la salida del host. Cuando es true, el host captura las excepciones producidas durante el inicio e intenta iniciar el servidor.

Clave: captureStartupErrors
Tipo: bool (true o 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.
Variable de entorno: <PREFIX_>CAPTURESTARTUPERRORS

Para establecer este valor, utilice la configuración o llame a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Si se habilita, o si el entorno es Development, la aplicación captura errores detallados.

Clave: detailedErrors
Tipo: bool (true o 1)
Predeterminado: false
Variable de entorno: <PREFIX_>_DETAILEDERRORS

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HostingStartupAssemblies

Una cadena delimitada por punto y coma de ensamblados de inicio de hospedaje para cargar en el inicio. 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. 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.

Clave: hostingStartupAssemblies
Tipo: string
Predeterminado: Cadena vacía
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HostingStartupExcludeAssemblies

Una cadena delimitada por punto y coma de ensamblados de inicio de hospedaje para excluir en el inicio.

Clave: hostingStartupExcludeAssemblies
Tipo: string
Predeterminado: Cadena vacía
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HTTPS_Port

Puerto de redireccionamiento HTTPS. Se usa en Exigir HTTPS.

Clave: https_port
Tipo: string
Predeterminado: no se ha establecido ningún valor predeterminado.
Variable de entorno: <PREFIX_>HTTPS_PORT

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

PreferHostingUrls

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.

Clave: preferHostingUrls
Tipo: bool (true o 1)
Predeterminado: true
Variable de entorno: <PREFIX_>_PREFERHOSTINGURLS

Para establecer este valor, use la variable de entorno o llame a PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Impide la carga automática de los ensamblados de inicio de hospedaje, incluidos los configurados por el ensamblado de la aplicación. Para obtener más información, vea Uso de ensamblados de inicio de hospedaje en ASP.NET Core.

Clave: preventHostingStartup
Tipo: bool (true o 1)
Predeterminado: false
Variable de entorno: <PREFIX_>_PREVENTHOSTINGSTARTUP

Para establecer este valor, use la variable de entorno o llame a UseSetting:

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

StartupAssembly

Ensamblado en el que se va a buscar la clase Startup.

Clave: startupAssembly
Tipo: string
Predeterminado: el ensamblado de la aplicación
Variable de entorno: <PREFIX_>STARTUPASSEMBLY

Para establecer este valor, use la variable de entorno o llame a UseStartup. UseStartup puede tomar un nombre del ensamblado (string) o un tipo (TStartup). Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

Direcciones URL

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. Por ejemplo: 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). El protocolo (http:// o https://) debe incluirse con cada dirección URL. Los formatos admitidos varían de un servidor a otro.

Clave: urls
Tipo: string
Predeterminado: http://localhost:5000 y https://localhost:5001
Variable de entorno: <PREFIX_>URLS

Para establecer este valor, use la variable de entorno o llame a UseUrls:

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

Kestrel tiene su propia API de configuración de punto de conexión. Para obtener más información, vea Configuración de puntos de conexión para el servidor web Kestrel de ASP.NET Core.

WebRoot

La propiedad IWebHostEnvironment.WebRootPath determina la ruta de acceso relativa a los recursos estáticos de la aplicación. Si la ruta de acceso no existe, se utiliza un proveedor de archivos no-op.

Clave: webroot
Tipo: string
Predeterminado: De manera predeterminada, es wwwroot. Debe existir la ruta de acceso a {raíz del contenido}/wwwroot.
Variable de entorno: <PREFIX_>WEBROOT

Para establecer este valor, use la variable de entorno o llame a UseWebRoot en IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para obtener más información, consulte:

Administración de la vigencia del host

Llame a los métodos en la implementación de IHost creada para iniciar y detener la aplicación. Estos métodos afectan a todas las implementaciones de IHostedService registradas en el contenedor de servicios.

Run

Run inicia la aplicación y bloquea el subproceso que realiza la llamada hasta que se cierre el host.

RunAsync

RunAsync inicia la aplicación y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre.

RunConsoleAsync

RunConsoleAsync habilita la compatibilidad de la consola, compila e inicia el host, y espera a Ctrl+C/SIGINT o SIGTERM para el apagado.

Iniciar

Start inicia el host de forma sincrónica.

StartAsync

StartAsync inicia el host y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre.

WaitForStartAsync se llama al inicio de StartAsync, que espera hasta que se complete antes de continuar. Esto se puede usar para retrasar el inicio hasta que lo indique un evento externo.

StopAsync

StopAsync intenta detener el host en el tiempo de espera proporcionado.

WaitForShutdown

WaitForShutdown bloquea el subproceso de llamada hasta que IHostLifetime desencadena el apagado, por ejemplo, a través de Ctrl+C/SIGINT o SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync devuelve Task, que se completa cuando se desencadena el cierre a través del token determinado y llama a StopAsync.

Control externo

El control directo de la vigencia del host se puede lograr mediante métodos a los que se puede llamar de forma externa:

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 plantillas de ASP.NET Core crean un host genérico de .NET Core (HostBuilder).

Definición de host

El host es un objeto que encapsula todos los recursos de la aplicación, como:

Inserción de dependencias (ID)
Registro
Configuración
Implementaciones de IHostedService

Configuración de un host

Normalmente se configura, compila y ejecuta el host por el código de la clase Program. El método Main realiza las acciones siguientes:

Llama a un método CreateHostBuilder para crear y configurar un objeto del generador.
Llama a los métodos Build y Run en el objeto del generador.

Las plantillas web de ASP.NET Core generan el código siguiente para crear un host genérico:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

En el código siguiente se crea un host genérico mediante una carga de trabajo que no es HTTP. La implementación de IHostedService se agrega al contenedor de DI:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

Para una carga de trabajo HTTP, el método Main es el mismo, pero CreateHostBuilder llama a ConfigureWebHostDefaults:

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

El código anterior se genera con las plantillas de ASP.NET Core.

Configuración predeterminada del generador

El método CreateDefaultBuilder realiza las acciones siguientes:

Establece la raíz de contenido en la ruta de acceso devuelta por GetCurrentDirectory.
Carga la configuración de host de:
- Variables de entorno con el prefijo DOTNET_.
- Argumentos de la línea de comandos.
Carga la configuración de aplicación de:
- appsettings.json.
- appsettings.{Environment}.json.
- Secretos del usuario cuando la aplicación se ejecuta en el entorno Development.
- Variables de entorno.
- Argumentos de la línea de comandos.
Agrega los siguientes proveedores de registro:
- Consola
- Depuración
- EventSource
- EventLog (solo si se ejecuta en Windows)
Permite la validación del ámbito y la validación de dependencias si el entorno es Desarrollo.

El método ConfigureWebHostDefaults realiza las acciones siguientes:

Carga la configuración de host desde las variables de entorno con el prefijo ASPNETCORE_.
Establece el servidor Kestrel como servidor web y lo configura por medio de los proveedores de configuración de hospedaje de la aplicación. Para conocer las opciones predeterminadas del servidor Kestrel, consulte Implementación del servidor web Kestrel en ASP.NET Core.
Agrega el middleware de filtrado de hosts.
Agrega middleware de encabezados reenviados si ASPNETCORE_FORWARDEDHEADERS_ENABLED es igual a true.
Permite la integración de IIS. Para consultar las opciones predeterminadas de IIS, vea Hospedaje de ASP.NET Core en Windows con IIS.

Servicios proporcionados por el marco de trabajo

Los servicios siguientes se registran de forma automática:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment/IWebHostEnvironment

Para más información sobre los servicios proporcionados por el marco, consulte Inserción de dependencias en ASP.NET Core.

IHostApplicationLifetime

El ejemplo siguiente es una implementación de IHostedService que registra los eventos IHostApplicationLifetime:

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

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

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

        return Task.CompletedTask;
    }

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

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

        // Perform post-startup activities here
    }

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

        // Perform on-stopping activities here
    }

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

        // Perform post-stopped activities here
    }
}

IHostLifetime

La implementación de IHostLifetime controla cuándo se inicia el host y cuándo se detiene. Se usa la última implementación registrada.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime es la implementación predeterminada de IHostLifetime. ConsoleLifetime:

escucha Ctrl+C/SIGINT o SIGTERM, y llama a StopApplication para iniciar el proceso de apagado.
Desbloquea extensiones como RunAsync y WaitForShutdownAsync.

IHostEnvironment

Permite insertar el servicio IHostEnvironment en una clase para obtener información sobre los valores siguientes:

ApplicationName
EnvironmentName
ContentRootPath

Las aplicaciones web implementan la interfaz IWebHostEnvironment, que hereda IHostEnvironment y agrega WebRootPath.

Configuración de host

La configuración de host se usa para las propiedades de la implementación de IHostEnvironment.

En el ejemplo siguiente se crea la configuración de host:

// using Microsoft.Extensions.Configuration;

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

Configuración de aplicaciones

Para más información, consulte Configuración en ASP.NET Core.

Configuración para todos los tipos de aplicaciones

ApplicationName

La propiedad IHostEnvironment.ApplicationName se establece desde la configuración de host durante la construcción de este.

Clave: applicationName
Tipo: string
Predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.
Variable de entorno: <PREFIX_>APPLICATIONNAME

Para establecer este valor, use la variable de entorno.

ContentRoot

La propiedad IHostEnvironment.ContentRootPath determina la ubicación en la que el host comienza a buscar archivos de contenido. Si no existe la ruta de acceso, el host no se puede iniciar.

Clave: contentRoot
Tipo: string
Predeterminado: carpeta donde se encuentra el ensamblado de la aplicación.
Variable de entorno: <PREFIX_>CONTENTROOT

Para establecer este valor, use la variable de entorno o llame a UseContentRoot en IHostBuilder:

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

Para obtener más información, consulte:

EnvironmentName

Clave: environment
Tipo: string
Predeterminado: Production
Variable de entorno: <PREFIX_>ENVIRONMENT

Para establecer este valor, use la variable de entorno o llame a UseEnvironment en IHostBuilder:

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

ShutdownTimeout

HostOptions.ShutdownTimeout establece el tiempo de espera para StopAsync. El valor predeterminado es cinco segundos. Durante el período de tiempo de espera, el host:

Activa IHostApplicationLifetime.ApplicationStopping.
Trata de detener los servicios hospedados y registra los errores que se producen en los servicios que no se puedan detener.

Clave: shutdownTimeoutSeconds
Tipo: int
Predeterminado: 5 segundos
Variable de entorno: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

Para establecer este valor, use la variable de entorno o configure HostOptions. El siguiente ejemplo establece el tiempo de espera en 20 segundos:

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

Configuración para las aplicaciones web

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

CaptureStartupErrors

Cuando es false, los errores durante el inicio provocan la salida del host. Cuando es true, el host captura las excepciones producidas durante el inicio e intenta iniciar el servidor.

Para establecer este valor, utilice la configuración o llame a CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

Si se habilita, o si el entorno es Development, la aplicación captura errores detallados.

Clave: detailedErrors
Tipo: bool (true o 1)
Predeterminado: false
Variable de entorno: <PREFIX_>_DETAILEDERRORS

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HostingStartupAssemblies

Clave: hostingStartupAssemblies
Tipo: string
Predeterminado: Cadena vacía
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HostingStartupExcludeAssemblies

Una cadena delimitada por punto y coma de ensamblados de inicio de hospedaje para excluir en el inicio.

Clave: hostingStartupExcludeAssemblies
Tipo: string
Predeterminado: Cadena vacía
Variable de entorno: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

HTTPS_Port

Puerto de redireccionamiento HTTPS. Se usa en Exigir HTTPS.

Clave: https_port
Tipo: string
Predeterminado: no se ha establecido ningún valor predeterminado.
Variable de entorno: <PREFIX_>HTTPS_PORT

Para establecer este valor, utilice la configuración o llame a UseSetting:

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

PreferHostingUrls

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.

Clave: preferHostingUrls
Tipo: bool (true o 1)
Predeterminado: true
Variable de entorno: <PREFIX_>_PREFERHOSTINGURLS

Para establecer este valor, use la variable de entorno o llame a PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Clave: preventHostingStartup
Tipo: bool (true o 1)
Predeterminado: false
Variable de entorno: <PREFIX_>_PREVENTHOSTINGSTARTUP

Para establecer este valor, use la variable de entorno o llame a UseSetting:

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

StartupAssembly

Ensamblado en el que se va a buscar la clase Startup.

Clave: startupAssembly
Tipo: string
Predeterminado: el ensamblado de la aplicación
Variable de entorno: <PREFIX_>STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

Direcciones URL

Clave: urls
Tipo: string
Predeterminado: http://localhost:5000 y https://localhost:5001
Variable de entorno: <PREFIX_>URLS

Para establecer este valor, use la variable de entorno o llame a UseUrls:

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

Kestrel tiene su propia API de configuración de punto de conexión. Para obtener más información, vea Implementación del servidor web Kestrel en ASP.NET Core.

WebRoot

Para establecer este valor, use la variable de entorno o llame a UseWebRoot en IWebHostBuilder:

webBuilder.UseWebRoot("public");

Para obtener más información, consulte:

Administración de la vigencia del host

Run

Run inicia la aplicación y bloquea el subproceso que realiza la llamada hasta que se cierre el host.

RunAsync

RunAsync inicia la aplicación y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre.

RunConsoleAsync

RunConsoleAsync habilita la compatibilidad de la consola, compila e inicia el host, y espera a Ctrl+C/SIGINT o SIGTERM para el apagado.

Iniciar

Start inicia el host de forma sincrónica.

StartAsync

StartAsync inicia el host y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre.

WaitForStartAsync se llama al inicio de StartAsync, que espera hasta que se complete antes de continuar. Esto se puede usar para retrasar el inicio hasta que lo indique un evento externo.

StopAsync

StopAsync intenta detener el host en el tiempo de espera proporcionado.

WaitForShutdown

WaitForShutdown bloquea el subproceso de llamada hasta que IHostLifetime desencadena el apagado, por ejemplo, a través de Ctrl+C/SIGINT o SIGTERM.

WaitForShutdownAsync

WaitForShutdownAsync devuelve Task, que se completa cuando se desencadena el cierre a través del token determinado y llama a StopAsync.

Control externo

El control directo de la vigencia del host se puede lograr mediante métodos a los que se puede llamar de forma externa:

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. El host es responsable de la administración del inicio y la duración de la aplicación.

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.

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

El host genérico es una novedad de ASP.NET Core 2.1 y no es adecuado para escenarios de hospedaje web. Para escenarios de hospedaje web, use el host web. 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.

Vea o descargue el código de ejemplo (cómo descargarlo)

Al ejecutar la aplicación de ejemplo en Visual Studio Code, use un terminal integrado o externo. No ejecute el ejemplo en internalConsole.

Para establecer la consola en Visual Studio Code:

Abra el archivo .vscode/launch.json.
En la configuración de .NET Core Launch (console) , busque la entrada console. Establezca el valor en externalTerminal o integratedTerminal.

Introducción

La biblioteca de host genérico está disponible en el espacio de nombres Microsoft.Extensions.Hosting y la proporciona el paquete Microsoft.Extensions.Hosting. El paquete Microsoft.Extensions.Hosting está incluido en el metapaquete Microsoft.AspNetCore.App (ASP.NET Core 2.1 o posterior).

IHostedService es el punto de entrada para la ejecución de código. Cada implementación de IHostedService se ejecuta en el orden de registro del servicio en 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.

Configuración de un host

IHostBuilder es el componente principal que usan las bibliotecas y aplicaciones para inicializar, compilar y ejecutar el host:

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

    await host.RunAsync();
}

Opciones

HostOptions configura opciones para IHost.

Tiempo de espera de apagado

ShutdownTimeout establece el tiempo de espera para StopAsync. El valor predeterminado es cinco segundos.

La siguiente configuración de opción en Program.Main aumenta el tiempo de espera de apagado predeterminado de 5 segundos a 20:

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

Servicios predeterminados

Estos son los servicios que se registran durante la inicialización del host:

Entorno (IHostingEnvironment)
HostBuilderContext
Configuración (IConfiguration)
IApplicationLifetime (Microsoft.Extensions.Hosting.Internal.ApplicationLifetime)
IHostLifetime (Microsoft.Extensions.Hosting.Internal.ConsoleLifetime)
IHost
Opciones (AddOptions)
Registro (AddLogging)

Configuración de host

La configuración del host se crea:

Llamando a métodos de extensión en IHostBuilder para establecer la raíz del contenido y el entorno.
Leyendo la configuración desde los proveedores de configuración de ConfigureHostConfiguration.

Métodos de extensión

Clave de aplicación (nombre)

La propiedad IHostingEnvironment.ApplicationName se establece desde la configuración del host durante la construcción de este. Para establecer el valor explícitamente, use HostDefaults.ApplicationKey:

Clave: applicationName
Tipo: string
Predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.
Establecer mediante: HostBuilderContext.HostingEnvironment.ApplicationName
Variable de entorno: <PREFIX_>APPLICATIONNAME (<PREFIX_> es opcional y definido por el usuario)

Raíz del contenido

Esta configuración determina la ubicación en la que el host comienza a buscar archivos de contenido.

Clave: contentRoot
Tipo: string
Predeterminado: la carpeta donde se encuentra el ensamblado de la aplicación.
Establecer mediante: UseContentRoot
Variable de entorno: <PREFIX_>CONTENTROOT (<PREFIX_> es opcional y definido por el usuario)

Si no existe la ruta de acceso, el host no se puede iniciar.

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

Para más información, consulte Aspectos básicos: Raíz del contenido.

Entorno

Establece el entorno de la aplicación.

Clave: environment
Tipo: string
Predeterminado: Production
Establecer mediante: UseEnvironment
Variable de entorno: <PREFIX_>ENVIRONMENT (<PREFIX_> es opcional y definido por el usuario)

El entorno se puede establecer en cualquier valor. Los valores definidos por el marco son Development, Staging y Production. Los valores no distinguen mayúsculas de minúsculas.

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

ConfigureHostConfiguration

ConfigureHostConfiguration usa un IConfigurationBuilder para crear una IConfiguration para el 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.

Se puede llamar varias veces a ConfigureHostConfiguration con resultados de suma. El host usa cualquier opción que establezca un valor en último lugar en una clave determinada.

De forma predeterminada no se incluye ningún proveedor. Debe especificar de forma explícita los proveedores de configuración que requiere la aplicación en ConfigureHostConfiguration, así como:

La configuración de archivo (por ejemplo, de un archivo hostsettings.json).
La configuración de la variable de entorno.
La configuración del argumento de la línea de comandos.
Otros proveedores de configuración necesarios.

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

Para agregar una configuración de la variable de entorno del host, llame a AddEnvironmentVariables en el generador del host. AddEnvironmentVariables acepta un prefijo opcional definido por el usuario. La aplicación de ejemplo usa el prefijo PREFIX_. El prefijo se quita cuando se leen las variables de entorno. 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.

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. En Visual Studio Code, las variables de entorno se pueden establecer en el archivo .vscode/launch.json durante el desarrollo. Para obtener más información, vea Usar varios entornos en ASP.NET Core.

La configuración de la línea de comandos se agrega llamando a 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.

hostsettings.json:

{
  "environment": "Development"
}

Se puede proporcionar una configuración adicional con las claves applicationName y contentRoot.

Configuración de HostBuilder de ejemplo con ConfigureHostConfiguration:

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

ConfigureAppConfiguration

La configuración de la aplicación se crea llamando a ConfigureAppConfiguration en la implementación de IHostBuilder. ConfigureAppConfiguration usa un IConfigurationBuilder para crear una IConfiguration para la aplicación. Se puede llamar varias veces a ConfigureAppConfiguration con resultados de suma. La aplicación usa cualquier opción que establezca un valor en último lugar en una clave determinada. La configuración creada por ConfigureAppConfiguration está disponible en HostBuilderContext.Configuration para las operaciones posteriores y en Services.

La configuración de la aplicación recibe automáticamente la configuración del host proporcionada por ConfigureHostConfiguration.

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

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

appsettings.Development.json:

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

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. La aplicación de ejemplo mueve sus archivos de configuración de aplicación JSON y hostsettings.json con el elemento <Content> siguiente:

<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. 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. Para obtener más información, vea Configuración en ASP.NET Core.

ConfigureServices

ConfigureServices agrega los servicios al contenedor de inserción de dependencias de la aplicación. Se puede llamar varias veces a ConfigureServices con resultados de suma.

Un servicio hospedado es una clase con lógica de tarea en segundo plano que implementa la interfaz IHostedService. Para obtener más información, vea 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:

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

ConfigureLogging

ConfigureLogging agrega un delegado para configurar el ILoggingBuilder proporcionado. Se puede llamar varias veces a ConfigureLogging con resultados de suma.

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

UseConsoleLifetime

UseConsoleLifetime escucha Ctrl+C/SIGINT o SIGTERM, y llama a StopApplication para iniciar el proceso de apagado. UseConsoleLifetime desbloquea extensiones como RunAsync y WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime ya está registrado previamente como la implementación de duración predeterminada. Se usa la última duración registrada.

var host = new HostBuilder()
    .UseConsoleLifetime()

Configuración del contenedor

Para permitir la conexión a otros contenedores, el host puede aceptar 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. UseServiceProviderFactory (IServiceProviderFactory<TContainerBuilder>) invalida el generador predeterminado utilizado para crear el proveedor de servicios de la aplicación.

La configuración personalizada del contenedor está administrada por el método ConfigureContainer. ConfigureContainer proporciona una experiencia fuertemente tipada para configurar el contenedor sobre la API de host subyacente. Se puede llamar varias veces a ConfigureContainer con resultados de suma.

Crear un contenedor de servicios de la aplicación:

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

Proporcionar un generador de contenedor de servicio:

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:

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

Extensibilidad

La extensibilidad de host se realiza con métodos de extensión en 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.

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:

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

Run

Run inicia la aplicación y bloquea el subproceso que realiza la llamada hasta que se cierre el host:

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

        host.Run();
    }
}

RunAsync

RunAsync inicia la aplicación y devuelve Task, que se completa cuando se desencadena el token de cancelación o el cierre:

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

        await host.RunAsync();
    }
}

RunConsoleAsync

RunConsoleAsync habilita la compatibilidad de la consola, compila e inicia el host, y espera a Ctrl+C/SIGINT o SIGTERM para el apagado.

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

        await hostBuilder.RunConsoleAsync();
    }
}

Start y StopAsync

Start inicia el host de forma sincrónica.

StopAsync intenta detener el host en el tiempo de espera proporcionado.

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 StopAsync

StartAsync inicia la aplicación.

StopAsync detiene la aplicación.

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

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

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdown se desencadena mediante IHostLifetime, como Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (escucha Ctrl+C/SIGINT o SIGTERM). WaitForShutdown llama a StopAsync.

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

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

WaitForShutdownAsync devuelve Task, que se completa cuando se desencadena el cierre a través del token determinado y llama a 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 externo

El control externo del host se puede lograr mediante métodos a los que se pueda llamar de forma externa:

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. Esto se puede usar para retrasar el inicio hasta que lo indique un evento externo.

Interfaz IHostingEnvironment

IHostingEnvironment proporciona información sobre el entorno de hospedaje de la aplicación. Use inserción de constructores para obtener IHostingEnvironment a fin de utilizar sus propiedades y métodos de extensión:

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.

Interfaz IApplicationLifetime

IApplicationLifetime permite actividades posteriores al inicio y cierre, incluidas las solicitudes de cierre estable. 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.

Token de cancelación	Se desencadena cuando…
ApplicationStarted	El host se ha iniciado completamente.
ApplicationStopped	El host está completando un apagado estable. Deben procesarse todas las solicitudes. El apagado se bloquea hasta que se complete este evento.
ApplicationStopping	El host está realizando un apagado estable. Puede que todavía se estén procesando las solicitudes. El apagado se bloquea hasta que se complete este evento.

Inserción de constructor del servicio IApplicationLifetime en cualquier clase. 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.

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. La siguiente clase usa StopApplication para cerrar de forma estable una aplicación cuando se llama al método Shutdown de esa clase:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Recursos adicionales

Tareas en segundo plano con servicios hospedados en ASP.NET Core
Vínculo de GitHub al origen de host genérico

Nota

Los enlaces de la documentación del origen de referencia de ASP.NET Core cargan la rama main del repositorio, que representa el desarrollo actual de la unidad de producto para la próxima versión de ASP.NET Core. Para seleccionar la rama de una versión diferente, use la lista desplegable Switch branches or tags (Cambiar ramas o etiquetas) para seleccionar la rama. Por ejemplo, seleccione la rama release/5.0 para la versión 5.0 de ASP.NET Core.

Host genérico de .NET en ASP.NET Core

Valore su experiencia

Definición de host

Configuración de un host

Configuración predeterminada del generador

Servicios proporcionados por el marco de trabajo

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Configuración de host

Configuración de aplicaciones

Configuración para todos los tipos de aplicaciones

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Deshabilitación de la recarga de configuración de aplicaciones al realizar un cambio

Configuración para las aplicaciones web

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

Direcciones URL

WebRoot

Administración de la vigencia del host

Run

RunAsync

RunConsoleAsync

Iniciar

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

Control externo

Definición de host

Configuración de un host

Configuración predeterminada del generador

Servicios proporcionados por el marco de trabajo

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Configuración de host

Configuración de aplicaciones

Configuración para todos los tipos de aplicaciones

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Configuración para las aplicaciones web

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

Direcciones URL

WebRoot

Administración de la vigencia del host

Run

RunAsync

RunConsoleAsync

Iniciar

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

Control externo

Introducción

Configuración de un host

Opciones

Tiempo de espera de apagado

Servicios predeterminados

Configuración de host

Métodos de extensión