Host web de ASP.NET Core

Artículo
11/06/2024

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión de .NET 9 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta 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 de .NET 9 de este artículo.

Las aplicaciones de 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. Como mínimo, el host configura un servidor y una canalización de procesamiento de solicitudes. El host también puede configurar el registro, la inserción de dependencias y la configuración.

En el artículo se explica el host web, que solo permanece disponible para compatibilidad con versiones anteriores: Las plantillas de ASP.NET Core crean WebApplicationBuilder y WebApplication, lo que se recomienda para las aplicaciones web. Para obtener más información sobre WebApplicationBuilder y WebApplication, consulta Migración de ASP.NET Core 5.0 a 6.0.

Configuración de un host

Crea un host con una instancia de IWebHostBuilder. Normalmente, esto se realiza en el punto de entrada de la aplicación, el método Main en Program.cs. Una aplicación típica llama a CreateDefaultBuilder para empezar a configurar un host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

El código que llama a CreateDefaultBuilder está en un método denominado CreateWebHostBuilder, que lo diferencia del código de Main que llama a Run en el objeto generador. Dicha diferencia es necesaria si usas herramientas de Entity Framework Core. Las herramientas esperan encontrar un método CreateWebHostBuilder al que pueden llamar en tiempo de diseño para configurar el host sin ejecutar la aplicación. Una alternativa consiste en implementar IDesignTimeDbContextFactory. Para obtener más información, consulta Creación de DbContext en tiempo de diseño.

CreateDefaultBuilder realiza las tareas siguientes:

Configura el servidor Kestrel como servidor web por medio de los proveedores de configuración de hospedaje de la aplicación. Para saber las opciones predeterminadas del servidor Kestrel, consulta Configuración de opciones para el servidor web Kestrel de ASP.NET Core.
Establece la raíz de contenido en la ruta de acceso devuelta por Directory.GetCurrentDirectory.
Carga la configuración de host de:
- Variables de entorno con el prefijo ASPNETCORE_ (por ejemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de la línea de comandos.
Carga la configuración de la aplicación en el siguiente orden:
- appsettings.json.
- appsettings.{Environment}.json.
- Secretos del usuario cuando la aplicación se ejecuta en el entorno Development por medio del ensamblado de entrada.
- Variables de entorno.
- Argumentos de la línea de comandos.
Configura el registro para la salida de consola y de depuración. El registro incluye reglas de filtrado de registros especificadas en una sección de configuración de registro de un archivo appsettings.json o appsettings.{Environment}.json.
Cuando se ejecuta detrás de IIS con el módulo ASP.NET Core, CreateDefaultBuilder habilita la integración de IIS, que configura la dirección base y el puerto de la aplicación. La integración de IIS también configura la aplicación para que capture errores de inicio. Para conocer las opciones predeterminadas de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.
Establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es desarrollo. Para más información, vea Validación del ámbito.

La configuración definida en CreateDefaultBuilder se puede reemplazar y aumentar con ConfigureAppConfiguration, ConfigureLogging y otros métodos y métodos de extensión de IWebHostBuilder. A continuación, se presentan algunos ejemplos:

ConfigureAppConfiguration se usa para especificar IConfiguration adicional para la aplicación. La siguiente llamada ConfigureAppConfiguration agrega un delegado para incluir la configuración de la aplicación en el archivo appsettings.xml. Es posible llamar a ConfigureAppConfiguration varias veces. Tenga en cuenta que esta configuración no se aplica al host (por ejemplo, direcciones URL de servidor o entorno). Vea la sección Valores de configuración de host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
La siguiente llamada a ConfigureLogging agrega un delegado para configurar el nivel de registro mínimo (SetMinimumLevel) a LogLevel.Warning. Esta configuración reemplaza la configuración de appsettings.Development.json (LogLevel.Debug) y appsettings.Production.json (LogLevel.Error) configurada mediante CreateDefaultBuilder. Es posible llamar a ConfigureLogging varias veces.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
La siguiente llamada a ConfigureKestrel reemplaza el valor predeterminado de Limits.MaxRequestBodySize de 30 000 000 bytes establecido al configurar Kestrel mediante CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

La raíz del contenido determina la ubicación en la que el host busca archivos de contenido como, por ejemplo, archivos de vista MVC. Cuando la aplicación se inicia desde la carpeta raíz del proyecto, esta se utiliza como la raíz del contenido. Este es el valor predeterminado usado en Visual Studio y las nuevas plantillas dotnet.

Para más información sobre la configuración de la aplicación, consulte Configuración en ASP.NET Core.

Nota

Como alternativa al uso del método estático CreateDefaultBuilder, la creación de un host desde WebHostBuilder es un enfoque compatible con ASP.NET Core 2.x.

Al configurar un host, se pueden proporcionar los métodos Configure y ConfigureServices. Si se especifica una clase Startup, debe definir un método Configure. Para obtener más información, vea Inicio de la aplicación en ASP.NET Core. Varias llamadas a ConfigureServices se anexan entre sí. Varias llamadas a Configure o UseStartup en el WebHostBuilder reemplazan la configuración anterior.

Valores de configuración de host

WebHostBuilder se basa en los siguientes métodos para establecer los valores de configuración del host:

Configuración del generador de host, que incluye las variables de entorno con el formato ASPNETCORE_{configurationKey}. Por ejemplo: ASPNETCORE_ENVIRONMENT.
Extensions como UseContentRoot y UseConfiguration (vea la sección Invalidación de la configuración).
UseSetting y la clave asociada. Al establecer un valor con UseSetting, el valor se establece como una cadena, independientemente del tipo.

El host usa cualquier opción que establece un valor en último lugar. Para obtener más información, consulte Invalidación de la configuración en la sección siguiente.

Clave de aplicación (nombre)

La propiedad IWebHostEnvironment.ApplicationName se establece automáticamente cuando se llama a UseStartup o Configure durante la construcción del host. El valor se establece en el nombre del ensamblado que contiene el punto de entrada de la aplicación. Para establecer el valor explícitamente, use WebHostDefaults.ApplicationKey:

Clave: nombreDeAplicación
Tipo: cadena
Valor predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar errores de inicio

Esta configuración controla la captura de errores de inicio.

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.
Establecer mediante: CaptureStartupErrors
Variable de entorno: ASPNETCORE_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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raíz del contenido

Esta configuración determina la ubicación en la que ASP.NET Core comienza a buscar archivos de contenido.

Clave: contentRoot
Tipo: cadena
Predeterminado: la carpeta donde se encuentra el ensamblado de la aplicación.
Establecer mediante: UseContentRoot
Variable de entorno: ASPNETCORE_CONTENTROOT

La raíz del contenido también se usa como la ruta de acceso base para la raíz web. Si no existe la ruta de acceso de la raíz web, el host no se puede iniciar.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obtener más información, consulte:

Errores detallados

Determina si se deben capturar los errores detallados.

Clave: detailedErrors
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_DETAILEDERRORS

Cuando se habilita (o cuando el entorno está establecido en Development), la aplicación captura excepciones detalladas.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Entorno

Establece el entorno de la aplicación.

Clave: environment
Tipo: cadena
Predeterminado: Producción
Establecer mediante: UseEnvironment
Variable de entorno: ASPNETCORE_ENVIRONMENT

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. De forma predeterminada, el entorno se lee desde la variable de entorno ASPNETCORE_ENVIRONMENT. Cuando se usa Visual Studio, las variables de entorno se pueden establecer en el archivo launchSettings.json. Para obtener más información, consulte Usar varios entornos en ASP.NET Core.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Ensamblados de inicio de hospedaje

Establece los ensamblados de inicio de hospedaje de la aplicación.

Clave: hostingStartupAssemblies
Tipo: cadena
Predeterminado: Cadena vacía
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_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.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Puerto HTTPS

Establece el puerto HTTPS al que redirigir si obtienes una conexión que no es HTTPS. Se usa en Exigir HTTPS. Esta configuración no hace que el servidor escuche en el puerto especificado. Es decir, es posible redirigir accidentalmente las solicitudes a un puerto sin usar.

Clave: https_port
Tipo: cadena
Predeterminado: no se ha establecido ningún valor predeterminado.
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HTTPS_PORT

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Puertos HTTPS

Establece los puertos en los que escuchar para conexiones HTTPS.

Clave: https_ports Tipo: cadena
Predeterminado: no se ha establecido ningún valor predeterminado.
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_ports", "8080")

Ensamblados de exclusión de inicio de hospedaje

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

Clave: hostingStartupExcludeAssemblies
Tipo: cadena
Predeterminado: Cadena vacía
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferir las direcciones URL de hospedaje

Indica si el host debe escuchar en las direcciones URL configuradas con WebHostBuilder en lugar de las que estén configuradas con la implementación de IServer.

Clave: preferHostingUrls
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: PreferHostingUrls
Variable de entorno: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Evitar el inicio de hospedaje

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
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

Direcciones URL de servidor

Indica las direcciones IP o las direcciones de host con los puertos y protocolos en que el servidor debe escuchar las solicitudes.

Clave: urls
Tipo: cadena
Predeterminado: http://localhost:5000
Establecer mediante: UseUrls
Variable de entorno: ASPNETCORE_URLS

Se establece una lista de prefijos de URL separados por punto y coma (;) a los que debe responder el servidor. 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.

WebHost.CreateDefaultBuilder(args)
    .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.

Tiempo de espera de apagado

Especifica la cantidad de tiempo que se espera hasta el cierre del host web.

Clave: shutdownTimeoutSeconds
Tipo: int
Predeterminado: 5
Establecer mediante: UseShutdownTimeout
Variable de entorno: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Aunque la clave acepta un int con UseSetting (por ejemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), el método de extensión UseShutdownTimeout toma TimeSpan.

Durante el período de tiempo de espera, el hospedaje:

Desencadena IApplicationLifetime.ApplicationStopping.
Trata de detener los servicios hospedados y registra cualquier error que se produzca 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.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Ensamblado de inicio

Determina el ensamblado en el que se va a buscar la clase Startup.

Clave: startupAssembly
Tipo: cadena
Predeterminado: el ensamblado de la aplicación
Establecer mediante: UseStartup
Variable de entorno: ASPNETCORE_STARTUPASSEMBLY

Se puede hacer referencia al ensamblado por su nombre (string) o su tipo (TStartup). Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raíz web

Establece la ruta de acceso relativa a los recursos estáticos de la aplicación.

Clave: webroot
Tipo: cadena
Predeterminado: De manera predeterminada, es wwwroot. Debe existir la ruta de acceso a {raíz del contenido}/wwwroot. Si la ruta de acceso no existe, se utiliza un proveedor de archivos no-op.
Establecer mediante: UseWebRoot
Variable de entorno: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obtener más información, consulta:

Invalidación de la configuración

Usa Configuración para configurar el host web. En el ejemplo siguiente, la configuración del host se especifica de forma opcional en un archivo hostsettings.json. Cualquier configuración que se cargue del archivo hostsettings.json se puede reemplazar por argumentos de línea de comandos. La configuración generada (en config) se utiliza para configurar el host con UseConfiguration. La configuración de IWebHostBuilder se agrega a la de la aplicación, pero lo contrario no es aplicable: ConfigureAppConfiguration no afecta a la configuración de IWebHostBuilder.

Reemplazar primero la configuración proporcionada por UseUrls por la de hostsettings.json y, luego, por la del argumento de línea de comandos:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Nota

UseConfiguration solo copia las claves del elemento IConfiguration proporcionado a la configuración del generador de host. Por consiguiente, el hecho de configurar reloadOnChange: true para los archivos de configuración XML, JSON e INI no tiene ningún efecto.

Para especificar el host que se ejecuta en una dirección URL determinada, se puede pasar el valor deseado desde un símbolo del sistema al ejecutar dotnet run. El argumento de línea de comandos reemplaza el valor urls del archivo hostsettings.json, y el servidor efectúa la escucha en el puerto 8080:

dotnet run --urls "http://*:8080"

Administración del host

Run

El método Run inicia la aplicación web y bloquea el subproceso que realiza la llamada hasta que se apague el host:

host.Run();

Iniciar

Ejecuta el host de manera que se evite un bloqueo mediante una llamada a su método Start:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Si se pasa una lista de direcciones URL al método Start, la escucha se produce en las direcciones URL especificadas:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

La aplicación puede inicializar un nuevo host usando los valores preconfigurados de CreateDefaultBuilder mediante un método práctico estático. Estos métodos inician el servidor sin la salida de la consola y con WaitForShutdown esperando una interrupción (Ctrl-C/SIGINT o SIGTERM):

Start(RequestDelegate app)

Start con RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Realice una solicitud en el explorador a http://localhost:5000 para recibir la respuesta "Hello World!" WaitForShutdown se bloquea hasta que se emite una interrupción (Ctrl-C/SIGINT o SIGTERM). La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.

Start(url de cadena, RequestDelegate app)

Start con una dirección URL y RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(RequestDelegate app) , excepto que la aplicación responde en http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Use una instancia de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar el middleware de enrutamiento:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Utilice las siguientes solicitudes de explorador con el ejemplo:

Request	Respuesta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Produce una excepción con la cadena "ooops!"
`http://localhost:5000/throw`	Produce una excepción con la cadena "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Hello World!

WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM). La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use una dirección URL y una instancia de IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(Action<IRouteBuilder> routeBuilder), salvo que la aplicación responde en http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Proporciona un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

StartWith(string url, Action<IApplicationBuilder> app)

Proporcione una dirección URL y un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que StartWith(Action<IApplicationBuilder> app), salvo que la aplicación responde en http://localhost:8080.

Interfaz IWebHostEnvironment

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

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

Puede utilizarse un enfoque convencional para configurar la aplicación en el inicio según el entorno. Como alternativa, inserte IWebHostEnvironment en el constructor Startup para su uso en ConfigureServices:

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Nota

Además del método de extensión IsDevelopment, IWebHostEnvironment ofrece los métodos IsStaging, IsProduction y IsEnvironment(string environmentName). Para obtener más información, consulte Usar varios entornos en ASP.NET Core.

El servicio IWebHostEnvironment también se puede insertar directamente en el método Configure para configurar la canalización de procesamiento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironment puede insertarse en el método Invoke al crear middleware personalizado:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interfaz IHostApplicationLifetime

IHostApplicationLifetime permite actividades posteriores al inicio y apagado. 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.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // 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 IHostApplicationLifetime _appLifetime;

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

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

Validación del ámbito

CreateDefaultBuilder establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es Development.

Cuando ValidateScopes está establecido en true, el proveedor de servicios predeterminado realiza comprobaciones para confirmar lo siguiente:

Los servicios con ámbito no se resuelven directa o indirectamente desde el proveedor de servicios raíz.
Los servicios con ámbito no se insertan directa o indirectamente en singletons.

El proveedor de servicios raíz se crea cuando se llama a BuildServiceProvider. La vigencia del proveedor de servicios raíz es la misma que la de la aplicación o el servidor cuando el proveedor se inicia con la aplicación, y se elimina cuando la aplicación se cierra.

De la eliminación de los servicios con ámbito se encarga el contenedor que los creó. Si un servicio con ámbito se crea en el contenedor raíz, su vigencia sube a la del singleton, ya que solo lo puede eliminar el contenedor raíz cuando la aplicación o el servidor se cierran. Al validar los ámbitos de servicio, este tipo de situaciones se detectan cuando se llama a BuildServiceProvider.

Para validar los ámbitos siempre, incluso en el entorno de producción, configure ServiceProviderOptions con UseDefaultServiceProvider en el generador de hosts:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Recursos adicionales

En el artículo se explica el host web, que solo permanece disponible para compatibilidad con versiones anteriores: Las plantillas de ASP.NET Core crean un host genérico de .NET, que se recomienda para todo tipo de aplicaciones.

Configuración de un host

Cree un host con una instancia de IWebHostBuilder. Normalmente, esto se realiza en el punto de entrada de la aplicación, el método Main.

En las plantillas de proyecto, Main se encuentra en Program.cs. Una aplicación típica llama a CreateDefaultBuilder para empezar a configurar un host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder realiza las tareas siguientes:

Configura el servidor Kestrel como servidor web por medio de los proveedores de configuración de hospedaje de la aplicación. Para saber las opciones predeterminadas del servidor Kestrel, consulta Configuración de opciones para el servidor web Kestrel de ASP.NET Core.
Establece la raíz de contenido en la ruta de acceso devuelta por Directory.GetCurrentDirectory.
Carga la configuración de host de:
- Variables de entorno con el prefijo ASPNETCORE_ (por ejemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de la línea de comandos.
Carga la configuración de la aplicación en el siguiente orden:
- appsettings.json.
- appsettings.{Environment}.json.
- Secretos del usuario cuando la aplicación se ejecuta en el entorno Development por medio del ensamblado de entrada.
- Variables de entorno.
- Argumentos de la línea de comandos.
Configura el registro para la salida de consola y de depuración. El registro incluye reglas de filtrado de registros especificadas en una sección de configuración de registro de un archivo appsettings.json o appsettings.{Environment}.json.
Cuando se ejecuta detrás de IIS con el módulo ASP.NET Core, CreateDefaultBuilder habilita la integración de IIS, que configura la dirección base y el puerto de la aplicación. La integración de IIS también configura la aplicación para que capture errores de inicio. Para conocer las opciones predeterminadas de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.
Establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es desarrollo. Para más información, vea Validación del ámbito.

ConfigureAppConfiguration se usa para especificar IConfiguration adicional para la aplicación. La siguiente llamada ConfigureAppConfiguration agrega un delegado para incluir la configuración de la aplicación en el archivo appsettings.xml. Es posible llamar a ConfigureAppConfiguration varias veces. Tenga en cuenta que esta configuración no se aplica al host (por ejemplo, direcciones URL de servidor o entorno). Vea la sección Valores de configuración de host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
La siguiente llamada a ConfigureLogging agrega un delegado para configurar el nivel de registro mínimo (SetMinimumLevel) a LogLevel.Warning. Esta configuración reemplaza la configuración de appsettings.Development.json (LogLevel.Debug) y appsettings.Production.json (LogLevel.Error) configurada mediante CreateDefaultBuilder. Es posible llamar a ConfigureLogging varias veces.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
La siguiente llamada a ConfigureKestrel reemplaza el valor predeterminado de Limits.MaxRequestBodySize de 30 000 000 bytes establecido al configurar Kestrel mediante CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

Para más información sobre la configuración de la aplicación, consulte Configuración en ASP.NET Core.

Nota

Como alternativa al uso del método estático CreateDefaultBuilder, la creación de un host desde WebHostBuilder es un enfoque compatible con ASP.NET Core 2.x.

Valores de configuración de host

WebHostBuilder se basa en los siguientes métodos para establecer los valores de configuración del host:

Configuración del generador de host, que incluye las variables de entorno con el formato ASPNETCORE_{configurationKey}. Por ejemplo: ASPNETCORE_ENVIRONMENT.
Extensions como UseContentRoot y UseConfiguration (vea la sección Invalidación de la configuración).
UseSetting y la clave asociada. Al establecer un valor con UseSetting, el valor se establece como una cadena, independientemente del tipo.

El host usa cualquier opción que establece un valor en último lugar. Para obtener más información, consulte Invalidación de la configuración en la sección siguiente.

Clave de aplicación (nombre)

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar errores de inicio

Esta configuración controla la captura de errores de inicio.

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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raíz del contenido

Esta configuración determina la ubicación en la que ASP.NET Core comienza a buscar archivos de contenido.

La raíz del contenido también se usa como la ruta de acceso base para la raíz web. Si no existe la ruta de acceso de la raíz web, el host no se puede iniciar.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obtener más información, consulte:

Errores detallados

Determina si se deben capturar los errores detallados.

Clave: detailedErrors
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_DETAILEDERRORS

Cuando se habilita (o cuando el entorno está establecido en Development), la aplicación captura excepciones detalladas.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Entorno

Establece el entorno de la aplicación.

Clave: environment
Tipo: cadena
Predeterminado: Producción
Establecer mediante: UseEnvironment
Variable de entorno: ASPNETCORE_ENVIRONMENT

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Ensamblados de inicio de hospedaje

Establece los ensamblados de inicio de hospedaje de la aplicación.

Clave: hostingStartupAssemblies
Tipo: cadena
Predeterminado: Cadena vacía
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Puerto HTTPS

Establezca puerto de redirección HTTPS. Se usa en Exigir HTTPS.

Clave: https_port
Tipo: cadena
Predeterminado: no se ha establecido ningún valor predeterminado.
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Ensamblados de exclusión de inicio de hospedaje

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferir las direcciones URL de hospedaje

Indica si el host debe escuchar en las direcciones URL configuradas con WebHostBuilder en lugar de las que estén configuradas con la implementación de IServer.

Clave: preferHostingUrls
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: PreferHostingUrls
Variable de entorno: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Evitar el inicio de hospedaje

Clave: preventHostingStartup
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

Direcciones URL de servidor

Indica las direcciones IP o las direcciones de host con los puertos y protocolos en que el servidor debe escuchar las solicitudes.

Clave: urls
Tipo: cadena
Predeterminado: http://localhost:5000
Establecer mediante: UseUrls
Variable de entorno: ASPNETCORE_URLS

WebHost.CreateDefaultBuilder(args)
    .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.

Tiempo de espera de apagado

Especifica la cantidad de tiempo que se espera hasta el cierre del host web.

Clave: shutdownTimeoutSeconds
Tipo: int
Predeterminado: 5
Establecer mediante: UseShutdownTimeout
Variable de entorno: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Aunque la clave acepta un int con UseSetting (por ejemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), el método de extensión UseShutdownTimeout toma TimeSpan.

Durante el período de tiempo de espera, el hospedaje:

Desencadena IApplicationLifetime.ApplicationStopping.
Trata de detener los servicios hospedados y registra cualquier error que se produzca en los servicios que no se puedan detener.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Ensamblado de inicio

Determina el ensamblado en el que se va a buscar la clase Startup.

Clave: startupAssembly
Tipo: cadena
Predeterminado: el ensamblado de la aplicación
Establecer mediante: UseStartup
Variable de entorno: ASPNETCORE_STARTUPASSEMBLY

Se puede hacer referencia al ensamblado por su nombre (string) o su tipo (TStartup). Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raíz web

Establece la ruta de acceso relativa a los recursos estáticos de la aplicación.

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obtener más información, consulta:

Invalidación de la configuración

Reemplazar primero la configuración proporcionada por UseUrls por la de hostsettings.json y, luego, por la del argumento de línea de comandos:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Nota

dotnet run --urls "http://*:8080"

Administración del host

Run

El método Run inicia la aplicación web y bloquea el subproceso que realiza la llamada hasta que se apague el host:

host.Run();

Iniciar

Ejecuta el host de manera que se evite un bloqueo mediante una llamada a su método Start:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Si se pasa una lista de direcciones URL al método Start, la escucha se produce en las direcciones URL especificadas:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Start(RequestDelegate app)

Start con RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Start(url de cadena, RequestDelegate app)

Start con una dirección URL y RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(RequestDelegate app) , excepto que la aplicación responde en http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Use una instancia de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar el middleware de enrutamiento:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Utilice las siguientes solicitudes de explorador con el ejemplo:

Request	Respuesta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Produce una excepción con la cadena "ooops!"
`http://localhost:5000/throw`	Produce una excepción con la cadena "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Hello World!

WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM). La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use una dirección URL y una instancia de IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(Action<IRouteBuilder> routeBuilder), salvo que la aplicación responde en http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Proporciona un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

StartWith(string url, Action<IApplicationBuilder> app)

Proporcione una dirección URL y un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que StartWith(Action<IApplicationBuilder> app), salvo que la aplicación responde en http://localhost:8080.

Interfaz IWebHostEnvironment

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Nota

El servicio IWebHostEnvironment también se puede insertar directamente en el método Configure para configurar la canalización de procesamiento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironment puede insertarse en el método Invoke al crear middleware personalizado:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interfaz IHostApplicationLifetime

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.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // 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 IHostApplicationLifetime _appLifetime;

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

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

Validación del ámbito

CreateDefaultBuilder establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es Development.

Cuando ValidateScopes está establecido en true, el proveedor de servicios predeterminado realiza comprobaciones para confirmar lo siguiente:

Los servicios con ámbito no se resuelven directa o indirectamente desde el proveedor de servicios raíz.
Los servicios con ámbito no se insertan directa o indirectamente en singletons.

Para validar los ámbitos siempre, incluso en el entorno de producción, configure ServiceProviderOptions con UseDefaultServiceProvider en el generador de hosts:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Recursos adicionales

Configuración de un host

Cree un host con una instancia de IWebHostBuilder. Normalmente, esto se realiza en el punto de entrada de la aplicación, el método Main.

En las plantillas de proyecto, Main se encuentra en Program.cs. Una aplicación típica llama a CreateDefaultBuilder para empezar a configurar un host:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder realiza las tareas siguientes:

Configura el servidor Kestrel como servidor web 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.
Establece la raíz de contenido en la ruta de acceso devuelta por Directory.GetCurrentDirectory.
Carga la configuración de host de:
- Variables de entorno con el prefijo ASPNETCORE_ (por ejemplo, ASPNETCORE_ENVIRONMENT).
- Argumentos de la línea de comandos.
Carga la configuración de la aplicación en el siguiente orden:
- appsettings.json.
- appsettings.{Environment}.json.
- Secretos del usuario cuando la aplicación se ejecuta en el entorno Development por medio del ensamblado de entrada.
- Variables de entorno.
- Argumentos de la línea de comandos.
Configura el registro para la salida de consola y de depuración. El registro incluye reglas de filtrado de registros especificadas en una sección de configuración de registro de un archivo appsettings.json o appsettings.{Environment}.json.
Cuando se ejecuta detrás de IIS con el módulo ASP.NET Core, CreateDefaultBuilder habilita la integración de IIS, que configura la dirección base y el puerto de la aplicación. La integración de IIS también configura la aplicación para que capture errores de inicio. Para conocer las opciones predeterminadas de IIS, consulte Hospedaje de ASP.NET Core en Windows con IIS.
Establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es desarrollo. Para más información, vea Validación del ámbito.

ConfigureAppConfiguration se usa para especificar IConfiguration adicional para la aplicación. La siguiente llamada ConfigureAppConfiguration agrega un delegado para incluir la configuración de la aplicación en el archivo appsettings.xml. Es posible llamar a ConfigureAppConfiguration varias veces. Tenga en cuenta que esta configuración no se aplica al host (por ejemplo, direcciones URL de servidor o entorno). Vea la sección Valores de configuración de host.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
        config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
    })
    ...
```
La siguiente llamada a ConfigureLogging agrega un delegado para configurar el nivel de registro mínimo (SetMinimumLevel) a LogLevel.Warning. Esta configuración reemplaza la configuración de appsettings.Development.json (LogLevel.Debug) y appsettings.Production.json (LogLevel.Error) configurada mediante CreateDefaultBuilder. Es posible llamar a ConfigureLogging varias veces.
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureLogging(logging => 
    {
        logging.SetMinimumLevel(LogLevel.Warning);
    })
    ...
```
La siguiente llamada a ConfigureKestrel reemplaza el valor predeterminado de Limits.MaxRequestBodySize de 30 000 000 bytes establecido al configurar Kestrel mediante CreateDefaultBuilder:
```
WebHost.CreateDefaultBuilder(args)
    .ConfigureKestrel((context, options) =>
    {
        options.Limits.MaxRequestBodySize = 20000000;
    });
```

Para más información sobre la configuración de la aplicación, consulte Configuración en ASP.NET Core.

Nota

Como alternativa al uso del método estático CreateDefaultBuilder, la creación de un host desde WebHostBuilder es un enfoque compatible con ASP.NET Core 2.x.

Valores de configuración de host

WebHostBuilder se basa en los siguientes métodos para establecer los valores de configuración del host:

Configuración del generador de host, que incluye las variables de entorno con el formato ASPNETCORE_{configurationKey}. Por ejemplo: ASPNETCORE_ENVIRONMENT.
Extensions como UseContentRoot y UseConfiguration (vea la sección Invalidación de la configuración).
UseSetting y la clave asociada. Al establecer un valor con UseSetting, el valor se establece como una cadena, independientemente del tipo.

El host usa cualquier opción que establece un valor en último lugar. Para obtener más información, consulte Invalidación de la configuración en la sección siguiente.

Clave de aplicación (nombre)

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

Capturar errores de inicio

Esta configuración controla la captura de errores de inicio.

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.

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raíz del contenido

Esta configuración determina la ubicación en la que ASP.NET Core comienza a buscar archivos de contenido.

La raíz del contenido también se usa como la ruta de acceso base para la raíz web. Si no existe la ruta de acceso de la raíz web, el host no se puede iniciar.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

Para obtener más información, consulte:

Errores detallados

Determina si se deben capturar los errores detallados.

Clave: detailedErrors
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_DETAILEDERRORS

Cuando se habilita (o cuando el entorno está establecido en Development), la aplicación captura excepciones detalladas.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Entorno

Establece el entorno de la aplicación.

Clave: environment
Tipo: cadena
Predeterminado: Producción
Establecer mediante: UseEnvironment
Variable de entorno: ASPNETCORE_ENVIRONMENT

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

Ensamblados de inicio de hospedaje

Establece los ensamblados de inicio de hospedaje de la aplicación.

Clave: hostingStartupAssemblies
Tipo: cadena
Predeterminado: Cadena vacía
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

Puerto HTTPS

Establezca puerto de redirección HTTPS. Se usa en Exigir HTTPS.

Clave: https_port
Tipo: cadena
Predeterminado: no se ha establecido ningún valor predeterminado.
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

Ensamblados de exclusión de inicio de hospedaje

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

Preferir las direcciones URL de hospedaje

Indica si el host debe escuchar en las direcciones URL configuradas con WebHostBuilder en lugar de las que estén configuradas con la implementación de IServer.

Clave: preferHostingUrls
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: PreferHostingUrls
Variable de entorno: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

Evitar el inicio de hospedaje

Clave: preventHostingStartup
Tipo: bool (true o 1)
Valor predeterminado: false
Establecer mediante: UseSetting
Variable de entorno: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

Direcciones URL de servidor

Indica las direcciones IP o las direcciones de host con los puertos y protocolos en que el servidor debe escuchar las solicitudes.

Clave: urls
Tipo: cadena
Predeterminado: http://localhost:5000
Establecer mediante: UseUrls
Variable de entorno: ASPNETCORE_URLS

WebHost.CreateDefaultBuilder(args)
    .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.

Tiempo de espera de apagado

Especifica la cantidad de tiempo que se espera hasta el cierre del host web.

Clave: shutdownTimeoutSeconds
Tipo: int
Predeterminado: 5
Establecer mediante: UseShutdownTimeout
Variable de entorno: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

Aunque la clave acepta un int con UseSetting (por ejemplo, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), el método de extensión UseShutdownTimeout toma TimeSpan.

Durante el período de tiempo de espera, el hospedaje:

Desencadena IApplicationLifetime.ApplicationStopping.
Trata de detener los servicios hospedados y registra cualquier error que se produzca en los servicios que no se puedan detener.

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

Ensamblado de inicio

Determina el ensamblado en el que se va a buscar la clase Startup.

Clave: startupAssembly
Tipo: cadena
Predeterminado: el ensamblado de la aplicación
Establecer mediante: UseStartup
Variable de entorno: ASPNETCORE_STARTUPASSEMBLY

Se puede hacer referencia al ensamblado por su nombre (string) o su tipo (TStartup). Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")

WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

Raíz web

Establece la ruta de acceso relativa a los recursos estáticos de la aplicación.

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

Para obtener más información, consulta:

Invalidación de la configuración

Reemplazar primero la configuración proporcionada por UseUrls por la de hostsettings.json y, luego, por la del argumento de línea de comandos:

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

Nota

dotnet run --urls "http://*:8080"

Administración del host

Run

El método Run inicia la aplicación web y bloquea el subproceso que realiza la llamada hasta que se apague el host:

host.Run();

Iniciar

Ejecuta el host de manera que se evite un bloqueo mediante una llamada a su método Start:

using (host)
{
    host.Start();
    Console.ReadLine();
}

Si se pasa una lista de direcciones URL al método Start, la escucha se produce en las direcciones URL especificadas:

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

Start(RequestDelegate app)

Start con RequestDelegate:

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Start(url de cadena, RequestDelegate app)

Start con una dirección URL y RequestDelegate:

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(RequestDelegate app) , excepto que la aplicación responde en http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)

Use una instancia de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar el middleware de enrutamiento:

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

Utilice las siguientes solicitudes de explorador con el ejemplo:

Request	Respuesta
`http://localhost:5000/hello/Martin`	Hello, Martin!
`http://localhost:5000/buenosdias/Catrina`	Buenos dias, Catrina!
`http://localhost:5000/throw/ooops!`	Produce una excepción con la cadena "ooops!"
`http://localhost:5000/throw`	Produce una excepción con la cadena "Uh oh!"
`http://localhost:5000/Sante/Kevin`	Sante, Kevin!
`http://localhost:5000`	Hello World!

WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM). La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.

Start(string url, Action<IRouteBuilder> routeBuilder)

Use una dirección URL y una instancia de IRouteBuilder:

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que Start(Action<IRouteBuilder> routeBuilder), salvo que la aplicación responde en http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)

Proporciona un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

StartWith(string url, Action<IApplicationBuilder> app)

Proporcione una dirección URL y un delegado para configurar IApplicationBuilder:

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

Produce el mismo resultado que StartWith(Action<IApplicationBuilder> app), salvo que la aplicación responde en http://localhost:8080.

Interfaz IWebHostEnvironment

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

Nota

El servicio IWebHostEnvironment también se puede insertar directamente en el método Configure para configurar la canalización de procesamiento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

IWebHostEnvironment puede insertarse en el método Invoke al crear middleware personalizado:

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

Interfaz IHostApplicationLifetime

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.

public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // 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 IHostApplicationLifetime _appLifetime;

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

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

Validación del ámbito

CreateDefaultBuilder establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es Development.

Cuando ValidateScopes está establecido en true, el proveedor de servicios predeterminado realiza comprobaciones para confirmar lo siguiente:

Los servicios con ámbito no se resuelven directa o indirectamente desde el proveedor de servicios raíz.
Los servicios con ámbito no se insertan directa o indirectamente en singletons.

Para validar los ámbitos siempre, incluso en el entorno de producción, configure ServiceProviderOptions con UseDefaultServiceProvider en el generador de hosts:

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

Compartir a través de

Host web de ASP.NET Core

Configuración de un host

Valores de configuración de host

Clave de aplicación (nombre)

Capturar errores de inicio

Raíz del contenido

Errores detallados

Entorno

Ensamblados de inicio de hospedaje

Puerto HTTPS

Puertos HTTPS

Ensamblados de exclusión de inicio de hospedaje

Preferir las direcciones URL de hospedaje

Evitar el inicio de hospedaje

Direcciones URL de servidor

Tiempo de espera de apagado

Ensamblado de inicio

Raíz web

Invalidación de la configuración

Administración del host

Interfaz IWebHostEnvironment

Interfaz IHostApplicationLifetime

Validación del ámbito

Recursos adicionales

Configuración de un host

Valores de configuración de host

Clave de aplicación (nombre)

Capturar errores de inicio

Raíz del contenido

Errores detallados

Entorno

Ensamblados de inicio de hospedaje

Puerto HTTPS

Ensamblados de exclusión de inicio de hospedaje

Preferir las direcciones URL de hospedaje

Evitar el inicio de hospedaje

Direcciones URL de servidor

Tiempo de espera de apagado

Ensamblado de inicio

Raíz web

Invalidación de la configuración

Administración del host

Interfaz IWebHostEnvironment

Interfaz IHostApplicationLifetime

Validación del ámbito

Recursos adicionales

Configuración de un host

Valores de configuración de host

Clave de aplicación (nombre)

Capturar errores de inicio

Raíz del contenido

Errores detallados

Entorno

Ensamblados de inicio de hospedaje

Puerto HTTPS

Ensamblados de exclusión de inicio de hospedaje

Preferir las direcciones URL de hospedaje

Evitar el inicio de hospedaje

Direcciones URL de servidor

Tiempo de espera de apagado

Ensamblado de inicio

Raíz web

Invalidación de la configuración

Administración del host

Interfaz IWebHostEnvironment

Interfaz IHostApplicationLifetime

Validación del ámbito

Recursos adicionales

Recursos adicionales