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

En este artículo se proporciona información sobre el uso del host genérico de .NET en ASP.NET Core.

Las plantillas de ASP.NET Core crean un objeto WebApplicationBuilder y un objeto WebApplication, que proporcionan una forma agilizada de configurar y ejecutar aplicaciones web sin una clase Startup. Para más información sobre WebApplicationBuilder y WebApplication, consulte WebApplicationBuilder.

Para información sobre cómo usar el 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 IHostedService.

Incluir todos los recursos interdependientes de la aplicación en un objeto permite controlar el inicio de la aplicación y apagado estable.

Configuración de un host

Normalmente, el código de la clase Program.cs configura, compila y ejecuta el host. El código siguiente crea un host con una implementación de IHostedService agregada al contenedor de DI.

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

Para una carga de trabajo HTTP, llame a ConfigureWebHostDefaults después de CreateDefaultBuilder:

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

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
  • Depurar
  • 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 obtener las opciones predeterminadas del servidor Kestrel, vea Kestrel.
• 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 conocer las opciones predeterminadas de IIS, consulte 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, que permite a las aplicaciones solicitar un apagado estable.

Al realizar un apagado estable, el host:

• Desencadena los controladores de eventos ApplicationStopping, lo que permite que la aplicación ejecute lógica antes de que comience el proceso de apagado.
• Detiene el servidor, lo que deshabilita las nuevas conexiones. El servidor espera a que se completen las solicitudes en las conexiones existentes, siempre y cuando el tiempo de espera de apagado lo permita. El servidor envía el encabezado de cierre de conexión en las solicitudes adicionales de las conexiones existentes.
• Desencadena los controladores de eventos ApplicationStopped, lo que permite que la aplicación ejecute la lógica después de que la aplicación se haya apagado.

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

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

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

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

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 (Windows), ⌘+C (macOS), 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 IWebHostEnvironment.

Configuración de host

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

La configuración del host está disponible desde HostBuilderContext.Configuration dentro de 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:

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(hostConfig =>
    {
        hostConfig.SetBasePath(Directory.GetCurrentDirectory());
        hostConfig.AddJsonFile("hostsettings.json", optional: true);
        hostConfig.AddEnvironmentVariables(prefix: "PREFIX_");
        hostConfig.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 desde DI. 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_, que aparece en la siguiente lista de valores como marcador de posición {PREFIX_}. Para más información, consulte la sección Configuración predeterminada del compilador y Configuración: variables de entorno.

ApplicationName

La propiedad IHostEnvironment.ApplicationName se establece a partir de 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 dónde 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("/path/to/content/root")
    // ...

Para obtener más información, consulte:

• Aspectos básicos: Raíz del contenido
• WebRoot

EnvironmentName

La propiedad IHostEnvironment.EnvironmentName 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.

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:

• Desencadena 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 tiempo de espera.

Clave: shutdownTimeoutSeconds
Tipo: int
Valor predeterminado: 30 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>(options =>
        {
            options.ShutdownTimeout = TimeSpan.FromSeconds(20);
        });
    });

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

De manera 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
Escriba: bool (true o false)
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_, que aparece en la siguiente lista de valores como marcador de posición {PREFIX_}.

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:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

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
Escriba: bool (true/1 o false/0)
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
Escriba: bool (true/1 o false/0)
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
Escriba: bool (true/1 o false/0)
Predeterminado:false
Variable de entorno: {PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

Clave: preventHostingStartup
Escriba: bool (true/1 o false/0)
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>();

SuppressStatusMessages

Cuando se habilita, suprime los mensajes de estado de inicio de hospedaje.

Clave: suppressStatusMessages
Escriba: bool (true/1 o false/0)
Predeterminado:false
Variable de entorno: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

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

• Aspectos básicos: Raíz web
• ContentRoot

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.

La diferencia entre los métodos Run* y Start* es que los métodos Run* esperan a que el host se complete antes de volver, mientras que los métodos Start* vuelven inmediatamente. Los métodos Run* se usan normalmente en aplicaciones de consola, mientras que los métodos Start* se usan normalmente en servicios de larga duración.

Ejecutar

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 con la consola, compila e inicia el host y espera a Ctrl+C/SIGINT (Windows), ⌘+C (macOS) o SIGTERM para apagarse.

Inicio

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. Este método se puede usar para retrasar el inicio hasta que lo señale 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, mediante Ctrl+C/SIGINT (Windows), ⌘+C (macOS) o SIGTERM.

WaitForShutdownAsync

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

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 vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).