Host genérico de .NET en ASP.NET Core
Nota:
Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 8 de este artículo.
Advertencia
Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulte la versión .NET 8 de este artículo.
Importante
Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.
Para la versión actual, consulte la versión .NET 8 de este artículo.
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.
- Variables de entorno con el prefijo
- 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 atrue
. - 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:
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:
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:
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 30 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:
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.
Las plantillas de ASP.NET Core crean un host genérico de .NET Core (HostBuilder).
En este artículo se proporciona información sobre el uso del host genérico de .NET en 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 IHostedService
.
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
yRun
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.
- Variables de entorno con el prefijo
- 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 atrue
. - 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:
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 (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:
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:
// 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 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("c:\\content-root")
//...
Para obtener más información, consulte:
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
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 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:
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
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:
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.
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).
En este artículo se proporciona información sobre el uso del host genérico de .NET en 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 IHostedService
.
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
yRun
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.
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.
- Variables de entorno con el prefijo
- 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 saber las opciones predeterminadas del servidor Kestrel, consulte 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 atrue
. - 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:
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 (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:
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:
// 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 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 configuración para el marcador de posición {PREFIX_}
.
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("c:\\content-root")
//...
Para obtener más información, consulte:
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
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
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
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 más información, consulte Servidor web Kestrel en 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.
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.
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));
}
}
}
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).