Host web de ASP.NET CoreASP.NET Core Web Host

Las aplicaciones de ASP.NET Core configuran e inician un host.ASP.NET Core apps configure and launch a host. El host es responsable de la administración del inicio y la duración de la aplicación.The host is responsible for app startup and lifetime management. Como mínimo, el host configura un servidor y una canalización de procesamiento de solicitudes.At a minimum, the host configures a server and a request processing pipeline. El host también puede configurar el registro, la inserción de dependencias y la configuración.The host can also set up logging, dependency injection, and configuration.

En el artículo se explica el host web, que solo permanece disponible para compatibilidad con versiones anteriores:This article covers the Web Host, which remains available only for backward compatibility. Se recomienda el host genérico para todos los tipos de aplicaciones.The Generic Host is recommended for all app types.

En este artículo se describe el host web, que sirve para hospedar aplicaciones web.This article covers the Web Host, which is for hosting web apps. Para otros tipos de aplicaciones, use el host genérico.For other kinds of apps, use the Generic Host.

Configuración de un hostSet up a host

Cree un host con una instancia de IWebHostBuilder.Create a host using an instance of IWebHostBuilder. Normalmente, esto se realiza en el punto de entrada de la aplicación, el método Main.This is typically performed in the app's entry point, the Main method.

En las plantillas de proyecto, Main se encuentra en Program.cs.In the project templates, Main is located in Program.cs. Una aplicación típica llama a CreateDefaultBuilder para empezar a configurar un host:A typical app calls CreateDefaultBuilder to start setting up a 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.The code that calls CreateDefaultBuilder is in a method named CreateWebHostBuilder, which separates it from the code in Main that calls Run on the builder object. Dicha diferencia es necesaria si usa herramientas de Entity Framework Core.This separation is required if you use Entity Framework Core tools. 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.The tools expect to find a CreateWebHostBuilder method that they can call at design time to configure the host without running the app. Una alternativa consiste en implementar IDesignTimeDbContextFactory.An alternative is to implement IDesignTimeDbContextFactory. Para obtener más información, consulte Creación de DbContext en tiempo de diseño.For more information, see Design-time DbContext Creation.

CreateDefaultBuilder realiza las tareas siguientes:CreateDefaultBuilder performs the following tasks:

La configuración definida en CreateDefaultBuilder se puede reemplazar y aumentar mediante ConfigureAppConfiguration, ConfigureLogging y otros métodos y métodos de extensión de IWebHostBuilder.The configuration defined by CreateDefaultBuilder can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. A continuación, se presentan algunos ejemplos:A few examples follow:

  • ConfigureAppConfiguration se usa para especificar IConfiguration adicionales para la aplicación.ConfigureAppConfiguration is used to specify additional IConfiguration for the app. La siguiente llamada ConfigureAppConfiguration agrega un delegado para incluir la configuración de la aplicación en el archivo appsettings.xml.The following ConfigureAppConfiguration call adds a delegate to include app configuration in the appsettings.xml file. Es posible llamar a ConfigureAppConfiguration varias veces.ConfigureAppConfiguration may be called multiple times. Tenga en cuenta que esta configuración no se aplica al host (por ejemplo, direcciones URL de servidor o entorno).Note that this configuration doesn't apply to the host (for example, server URLs or environment). Vea la sección Valores de configuración de host.See the Host configuration values section.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • La siguiente llamada ConfigureLogging agrega un delegado para configurar el nivel de registro mínimo (SetMinimumLevel) en LogLevel.Warning.The following ConfigureLogging call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. Esta configuración reemplaza la configuración de appsettings.Development.JSON (LogLevel.Debug) y appsettings.Production.JSON (LogLevel.Error) configurada mediante CreateDefaultBuilder.This setting overrides the settings in appsettings.Development.json (LogLevel.Debug) and appsettings.Production.json (LogLevel.Error) configured by CreateDefaultBuilder. Es posible llamar a ConfigureLogging varias veces.ConfigureLogging may be called multiple times.

    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:The following call to ConfigureKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    
  • La siguiente llamada a UseKestrel reemplaza el valor predeterminado de Limits.MaxRequestBodySize de 30 000 000 bytes establecido al configurar Kestrel mediante CreateDefaultBuilder:The following call to UseKestrel overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured by CreateDefaultBuilder:

    WebHost.CreateDefaultBuilder(args)
        .UseKestrel(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.The content root determines where the host searches for content files, such as MVC view files. Cuando la aplicación se inicia desde la carpeta raíz del proyecto, esta se utiliza como la raíz del contenido.When the app is started from the project's root folder, the project's root folder is used as the content root. Este es el valor predeterminado usado en Visual Studio y las nuevas plantillas dotnet.This is the default used in Visual Studio and the dotnet new templates.

Para obtener más información sobre la configuración de la aplicación, vea Configuración en ASP.NET Core.For more information on app configuration, see Configuración en ASP.NET Core.

Nota

Como alternativa al uso del método estático CreateDefaultBuilder, crear un host de WebHostBuilder es un enfoque compatible con ASP.NET Core 2.x.As an alternative to using the static CreateDefaultBuilder method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.

Al configurar un host, se pueden proporcionar los métodos Configure y ConfigureServices.When setting up a host, Configure and ConfigureServices methods can be provided. Si se especifica una clase Startup, debe definir un método Configure.If a Startup class is specified, it must define a Configure method. Para más información, consulte Inicio de la aplicación en ASP.NET Core.For more information, see Inicio de la aplicación en ASP.NET Core. Varias llamadas a ConfigureServices se anexan entre sí.Multiple calls to ConfigureServices append to one another. Varias llamadas a Configure o UseStartup en el WebHostBuilder reemplazan la configuración anterior.Multiple calls to Configure or UseStartup on the WebHostBuilder replace previous settings.

Valores de configuración de hostHost configuration values

WebHostBuilder se basa en los siguientes métodos para establecer los valores de configuración del host:WebHostBuilder relies on the following approaches to set the host configuration values:

  • Configuración del generador de host, que incluye las variables de entorno con el formato ASPNETCORE_{configurationKey}.Host builder configuration, which includes environment variables with the format ASPNETCORE_{configurationKey}. Por ejemplo: ASPNETCORE_ENVIRONMENT.For example, ASPNETCORE_ENVIRONMENT.
  • Extensiones como UseContentRoot y UseConfiguration (vea la sección Invalidación de la configuración).Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
  • UseSetting y la clave asociada.UseSetting and the associated key. Al establecer un valor con UseSetting, el valor se establece como una cadena, independientemente del tipo.When setting a value with UseSetting, the value is set as a string regardless of the type.

El host usa cualquier opción que establece un valor en último lugar.The host uses whichever option sets a value last. Para obtener más información, consulte Invalidación de la configuración en la sección siguiente.For more information, see Override configuration in the next section.

Clave de aplicación (nombre)Application Key (Name)

La propiedad IWebHostEnvironment.ApplicationName se establece automáticamente cuando se llama a UseStartup o Configure durante la construcción del host.The IWebHostEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called during host construction. El valor se establece en el nombre del ensamblado que contiene el punto de entrada de la aplicación.The value is set to the name of the assembly containing the app's entry point. Para establecer el valor explícitamente, use WebHostDefaults.ApplicationKey:To set the value explicitly, use the WebHostDefaults.ApplicationKey:

La propiedad IHostingEnvironment.ApplicationName se establece automáticamente cuando se llama a UseStartup o Configure durante la construcción del host.The IHostingEnvironment.ApplicationName property is automatically set when UseStartup or Configure is called during host construction. El valor se establece en el nombre del ensamblado que contiene el punto de entrada de la aplicación.The value is set to the name of the assembly containing the app's entry point. Para establecer el valor explícitamente, use WebHostDefaults.ApplicationKey:To set the value explicitly, use the WebHostDefaults.ApplicationKey:

Clave: nombreDeAplicaciónKey: applicationName
Tipo: cadenaType: string
Valor predeterminado: nombre del ensamblado que contiene el punto de entrada de la aplicación.Default: The name of the assembly containing the app's entry point.
Establecer mediante: UseSettingSet using: UseSetting
Variable de entorno: ASPNETCORE_APPLICATIONNAMEEnvironment variable: ASPNETCORE_APPLICATIONNAME

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

Capturar errores de inicioCapture Startup Errors

Esta configuración controla la captura de errores de inicio.This setting controls the capture of startup errors.

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

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

Raíz del contenidoContent root

Esta configuración determina la ubicación en la que ASP.NET Core comienza a buscar archivos de contenido.This setting determines where ASP.NET Core begins searching for content files.

Clave: contentRootKey: contentRoot
Tipo: cadenaType: string
Valor predeterminado: la carpeta donde se encuentra el ensamblado de la aplicación.Default: Defaults to the folder where the app assembly resides.
Establecer mediante: UseContentRootSet using: UseContentRoot
Variable de entorno: ASPNETCORE_CONTENTROOTEnvironment variable: ASPNETCORE_CONTENTROOT

La raíz del contenido también se usa como la ruta de acceso base para la raíz web.The content root is also used as the base path for the web root. Si no existe la ruta de acceso de la raíz web, el host no se puede iniciar.If the content root path doesn't exist, the host fails to start.

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

Para obtener más información, consulte:For more information, see:

Errores detalladosDetailed Errors

Determina si se deben capturar los errores detallados.Determines if detailed errors should be captured.

Clave: detailedErrorsKey: detailedErrors
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: falseDefault: false
Establecer mediante: UseSettingSet using: UseSetting
Variable de entorno: ASPNETCORE_DETAILEDERRORSEnvironment variable: ASPNETCORE_DETAILEDERRORS

Cuando se habilita (o cuando el entorno está establecido en Development), la aplicación captura excepciones detalladas.When enabled (or when the Environment is set to Development), the app captures detailed exceptions.

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

EntornoEnvironment

Establece el entorno de la aplicación.Sets the app's environment.

Clave: environmentKey: environment
Tipo: cadenaType: string
Valor predeterminado: ProducciónDefault: Production
Establecer mediante: UseEnvironmentSet using: UseEnvironment
Variable de entorno: ASPNETCORE_ENVIRONMENTEnvironment variable: ASPNETCORE_ENVIRONMENT

El entorno se puede establecer en cualquier valor.The environment can be set to any value. Los valores definidos por el marco son Development, Staging y Production.Framework-defined values include Development, Staging, and Production. Los valores no distinguen mayúsculas de minúsculas.Values aren't case sensitive. De forma predeterminada, el entorno se lee desde la variable de entorno ASPNETCORE_ENVIRONMENT.By default, the Environment is read from the ASPNETCORE_ENVIRONMENT environment variable. Cuando se usa Visual Studio, las variables de entorno se pueden establecer en el archivo launchSettings.json.When using Visual Studio, environment variables may be set in the launchSettings.json file. Para más información, consulte Usar varios entornos en ASP.NET Core.For more information, see Usar varios entornos en ASP.NET Core.

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

Ensamblados de inicio de hospedajeHosting Startup Assemblies

Establece los ensamblados de inicio de hospedaje de la aplicación.Sets the app's hosting startup assemblies.

Clave: hostingStartupAssembliesKey: hostingStartupAssemblies
Tipo: cadenaType: string
Valor predeterminado: Cadena vacíaDefault: Empty string
Establecer mediante: UseSettingSet using: UseSetting
Variable de entorno: ASPNETCORE_HOSTINGSTARTUPASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

Aunque el valor de configuración predeterminado es una cadena vacía, los ensamblados de inicio de hospedaje incluyen siempre el ensamblado de la aplicación.Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. Cuando se especifican los ensamblados de inicio de hospedaje, estos se agregan al ensamblado de la aplicación para que se carguen cuando la aplicación genera sus servicios comunes durante el inicio.When hosting startup assemblies are provided, they're added to the app's assembly for loading when the app builds its common services during startup.

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

Puerto HTTPSHTTPS Port

Establezca puerto de redirección HTTPS.Set the HTTPS redirect port. Se usa en Exigir HTTPS.Used in enforcing HTTPS.

Clave: https_port Tipo: cadena Valor predeterminado: no se ha establecido ningún valor predeterminado.Key: https_port Type: string Default: A default value isn't set. Establecer mediante: UseSetting Variable de entorno: ASPNETCORE_HTTPS_PORTSet using: UseSetting Environment variable: ASPNETCORE_HTTPS_PORT

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

Ensamblados de exclusión de inicio de hospedajeHosting Startup Exclude Assemblies

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

Clave: hostingStartupExcludeAssembliesKey: hostingStartupExcludeAssemblies
Tipo: cadenaType: string
Valor predeterminado: Cadena vacíaDefault: Empty string
Establecer mediante: UseSettingSet using: UseSetting
Variable de entorno: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIESEnvironment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

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

Preferir las direcciones URL de hospedajePrefer Hosting URLs

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.Indicates whether the host should listen on the URLs configured with the WebHostBuilder instead of those configured with the IServer implementation.

Clave: preferHostingUrlsKey: preferHostingUrls
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: trueDefault: true
Establecer mediante: PreferHostingUrlsSet using: PreferHostingUrls
Variable de entorno: ASPNETCORE_PREFERHOSTINGURLSEnvironment variable: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(false)

Evitar el inicio de hospedajePrevent Hosting Startup

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

Clave: preventHostingStartupKey: preventHostingStartup
Tipo: bool (true o 1)Type: bool (true or 1)
Valor predeterminado: falseDefault: false
Establecer mediante: UseSettingSet using: UseSetting
Variable de entorno: ASPNETCORE_PREVENTHOSTINGSTARTUPEnvironment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP

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

Direcciones URL de servidorServer URLs

Indica las direcciones IP o las direcciones de host con los puertos y protocolos en que el servidor debe escuchar las solicitudes.Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.

Clave: urlsKey: urls
Tipo: cadenaType: string
Predeterminado: http://localhost:5000Default: http://localhost:5000
Establecer mediante: UseUrlsSet using: UseUrls
Variable de entorno: ASPNETCORE_URLSEnvironment variable: ASPNETCORE_URLS

Se establece una lista de prefijos de URL separados por punto y coma (;) a los que debe responder el servidor.Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. Por ejemplo: http://localhost:123.For example, http://localhost:123. Use "*" para indicar que el servidor debe escuchar las solicitudes en cualquier dirección IP o nombre de host con el puerto y el protocolo especificados (por ejemplo, http://*:5000).Use "*" to indicate that the server should listen for requests on any IP address or hostname using the specified port and protocol (for example, http://*:5000). El protocolo (http:// o https://) debe incluirse con cada dirección URL.The protocol (http:// or https://) must be included with each URL. Los formatos admitidos varían de un servidor a otro.Supported formats vary among servers.

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.Kestrel has its own endpoint configuration API. Para más información, consulte Implementación del servidor web Kestrel en ASP.NET Core.For more information, see Implementación del servidor web Kestrel en ASP.NET Core.

Tiempo de espera de apagadoShutdown Timeout

Especifica la cantidad de tiempo que se espera hasta el cierre del host web.Specifies the amount of time to wait for Web Host to shut down.

Clave: shutdownTimeoutSecondsKey: shutdownTimeoutSeconds
Tipo: intType: int
Valor predeterminado: 5Default: 5
Establecer mediante: UseShutdownTimeoutSet using: UseShutdownTimeout
Variable de entorno: ASPNETCORE_SHUTDOWNTIMEOUTSECONDSEnvironment variable: 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.Although the key accepts an int with UseSetting (for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")), the UseShutdownTimeout extension method takes a TimeSpan.

Durante el período de tiempo de espera, el hospedaje:During the timeout period, hosting:

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

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

Ensamblado de inicioStartup Assembly

Determina el ensamblado en el que se va a buscar la clase Startup.Determines the assembly to search for the Startup class.

Clave: startupAssemblyKey: startupAssembly
Tipo: cadenaType: string
Valor predeterminado: el ensamblado de la aplicaciónDefault: The app's assembly
Establecer mediante: UseStartupSet using: UseStartup
Variable de entorno: ASPNETCORE_STARTUPASSEMBLYEnvironment variable: ASPNETCORE_STARTUPASSEMBLY

Se puede hacer referencia al ensamblado por su nombre (string) o su tipo (TStartup).The assembly by name (string) or type (TStartup) can be referenced. Si se llama a varios métodos UseStartup, la última llamada tiene prioridad.If multiple UseStartup methods are called, the last one takes precedence.

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

Raíz webWeb root

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

Clave: webrootKey: webroot
Tipo: cadenaType: string
Predeterminado: De manera predeterminada, es wwwroot.Default: The default is wwwroot. Debe existir la ruta de acceso a {raíz del contenido}/wwwroot.The path to {content root}/wwwroot must exist. Si la ruta de acceso no existe, se utiliza un proveedor de archivos no-op.If the path doesn't exist, a no-op file provider is used.
Establecer mediante: UseWebRootSet using: UseWebRoot
Variable de entorno: ASPNETCORE_WEBROOTEnvironment variable: ASPNETCORE_WEBROOT

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

Para obtener más información, consulte:For more information, see:

Invalidación de la configuraciónOverride configuration

Use Configuración para configurar el host web.Use Configuration to configure Web Host. En el ejemplo siguiente, la configuración del host se especifica de forma opcional en un archivo hostsettings.json.In the following example, host configuration is optionally specified in a hostsettings.json file. Cualquier configuración que se cargue del archivo hostsettings.json se puede reemplazar por argumentos de línea de comandos.Any configuration loaded from the hostsettings.json file may be overridden by command-line arguments. La configuración generada (en config) se usa para configurar el host con UseConfiguration.The built configuration (in config) is used to configure the host with 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.IWebHostBuilder configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration doesn't affect the IWebHostBuilder configuration.

Reemplazar primero la configuración proporcionada por UseUrls por la de hostsettings.json y, luego, por la del argumento de línea de comandos:Overriding the configuration provided by UseUrls with hostsettings.json config first, command-line argument config second:

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:hostsettings.json:

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

Nota

El método de extensión UseConfiguration no es capaz de analizar actualmente una sección de configuración devuelta por GetSection (por ejemplo, .UseConfiguration(Configuration.GetSection("section")).The UseConfiguration extension method isn't currently capable of parsing a configuration section returned by GetSection (for example, .UseConfiguration(Configuration.GetSection("section")). El método GetSection filtra las claves de configuración a la sección solicitada, pero deja el nombre de sección en las claves (por ejemplo, section:urls, section:environment).The GetSection method filters the configuration keys to the section requested but leaves the section name on the keys (for example, section:urls, section:environment). El método UseConfiguration espera que las claves coincidan con las claves WebHostBuilder (por ejemplo, urls, environment).The UseConfiguration method expects the keys to match the WebHostBuilder keys (for example, urls, environment). La presencia del nombre de sección en las claves evita que los valores de la sección configuren el host.The presence of the section name on the keys prevents the section's values from configuring the host. Este problema se corregirá en una versión futura.This issue will be addressed in an upcoming release. Para obtener más información y soluciones alternativas, consulte Passing configuration section into WebHostBuilder.UseConfiguration uses full keys (Pasar la sección de configuración a WebHostBuilder.UseConfiguration usa claves completas).For more information and workarounds, see Passing configuration section into WebHostBuilder.UseConfiguration uses full keys.

UseConfiguration solo copia las claves del elemento IConfiguration proporcionado a la configuración del generador de host.UseConfiguration only copies keys from the provided IConfiguration to the host builder configuration. Por consiguiente, el hecho de configurar reloadOnChange: true para los archivos de configuración XML, JSON e INI no tiene ningún efecto.Therefore, setting reloadOnChange: true for JSON, INI, and XML settings files has no effect.

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.To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing 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:The command-line argument overrides the urls value from the hostsettings.json file, and the server listens on port 8080:

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

Administración del hostManage the host

RunRun

El método Run inicia la aplicación web y bloquea el subproceso que realiza la llamada hasta que se apague el host:The Run method starts the web app and blocks the calling thread until the host is shut down:

host.Run();

IniciarStart

Ejecute el host de manera que se evite un bloqueo mediante una llamada a su método Start:Run the host in a non-blocking manner by calling its Start method:

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:If a list of URLs is passed to the Start method, it listens on the URLs specified:

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.The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder using a static convenience method. Estos métodos inician el servidor sin la salida de la consola y con WaitForShutdown esperando una interrupción (Ctrl-C/SIGINT o SIGTERM):These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):

Start(RequestDelegate app)Start(RequestDelegate app)

Start con RequestDelegate:Start with a RequestDelegate:

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

Haga una solicitud en el explorador a http://localhost:5000 para recibir la respuesta "Hello World!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(url de cadena, RequestDelegate app)Start(string url, RequestDelegate app)

Start con una dirección URL y RequestDelegate:Start with a URL and 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.Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080.

Start(Action<IRouteBuilder> routeBuilder)Start(Action<IRouteBuilder> routeBuilder)

Use una instancia de IRouteBuilder (Microsoft.AspNetCore.Routing) para usar el middleware de enrutamiento:Use an instance of IRouteBuilder (Microsoft.AspNetCore.Routing) to use routing middleware:

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:Use the following browser requests with the example:

RequestRequest RespuestaResponse
http://localhost:5000/hello/Martin Hello, Martin!Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!Buenos dias, Catrina!
http://localhost:5000/throw/ooops! Produce una excepción con la cadena "ooops!"Throws an exception with string "ooops!"
http://localhost:5000/throw Produce una excepción con la cadena "Uh oh!"Throws an exception with string "Uh oh!"
http://localhost:5000/Sante/Kevin Sante, Kevin!Sante, Kevin!
http://localhost:5000 Hello World!Hello World!

WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.The app displays the Console.WriteLine message and waits for a keypress to exit.

Start(string url, Action<IRouteBuilder> routeBuilder)Start(string url, Action<IRouteBuilder> routeBuilder)

Use una dirección URL y una instancia de IRouteBuilder:Use a URL and an instance of 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.Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080.

StartWith(Action<IApplicationBuilder> app)StartWith(Action<IApplicationBuilder> app)

Proporciona un delegado para configurar IApplicationBuilder:Provide a delegate to configure an 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();
}

Haga una solicitud en el explorador a http://localhost:5000 para recibir la respuesta "Hello World!"Make a request in the browser to http://localhost:5000 to receive the response "Hello World!" WaitForShutdown se bloquea hasta que se emite un salto (Ctrl-C/SIGINT o SIGTERM).WaitForShutdown blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. La aplicación muestra el mensaje Console.WriteLine y espera a que se pulse una tecla para salir.The app displays the Console.WriteLine message and waits for a keypress to exit.

StartWith(string url, Action<IApplicationBuilder> app)StartWith(string url, Action<IApplicationBuilder> app)

Proporcione una dirección URL y un delegado para configurar IApplicationBuilder:Provide a URL and a delegate to configure an 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.Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080.

Interfaz IWebHostEnvironmentIWebHostEnvironment interface

La interfaz IWebHostEnvironment proporciona información sobre el entorno de hospedaje web de la aplicación.The IWebHostEnvironment interface provides information about the app's web hosting environment. Use inserción de constructores para obtener IWebHostEnvironment a fin de utilizar sus propiedades y métodos de extensión:Use constructor injection to obtain the IWebHostEnvironment in order to use its properties and extension methods:

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.A convention-based approach can be used to configure the app at startup based on the environment. Como alternativa, inserte IWebHostEnvironment en el constructor Startup para su uso en ConfigureServices:Alternatively, inject the IWebHostEnvironment into the Startup constructor for use in 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).In addition to the IsDevelopment extension method, IWebHostEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Para más información, consulte Usar varios entornos en ASP.NET Core.For more information, see 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:The IWebHostEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

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:IWebHostEnvironment can be injected into the Invoke method when creating custom middleware:

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 IHostingEnvironmentIHostingEnvironment interface

La interfaz IHostingEnvironment proporciona información sobre el entorno de hospedaje web de la aplicación.The IHostingEnvironment interface provides information about the app's web hosting environment. Use inserción de constructores para obtener IHostingEnvironment a fin de utilizar sus propiedades y métodos de extensión:Use constructor injection to obtain the IHostingEnvironment in order to use its properties and extension methods:

public class CustomFileReader
{
    private readonly IHostingEnvironment _env;

    public CustomFileReader(IHostingEnvironment 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.A convention-based approach can be used to configure the app at startup based on the environment. Como alternativa, inserte IHostingEnvironment en el constructor Startup para su uso en ConfigureServices:Alternatively, inject the IHostingEnvironment into the Startup constructor for use in ConfigureServices:

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

    public IHostingEnvironment 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, IHostingEnvironment ofrece los métodos IsStaging, IsProduction y IsEnvironment(string environmentName).In addition to the IsDevelopment extension method, IHostingEnvironment offers IsStaging, IsProduction, and IsEnvironment(string environmentName) methods. Para más información, consulte Usar varios entornos en ASP.NET Core.For more information, see Usar varios entornos en ASP.NET Core.

El servicio IHostingEnvironment también se puede insertar directamente en el método Configure para configurar la canalización de procesamiento:The IHostingEnvironment service can also be injected directly into the Configure method for setting up the processing pipeline:

public void Configure(IApplicationBuilder app, IHostingEnvironment 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;
}

IHostingEnvironment puede insertarse en el método Invoke al crear middleware personalizado:IHostingEnvironment can be injected into the Invoke method when creating custom middleware:

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

    var contentRootPath = env.ContentRootPath;
}

Interfaz IHostApplicationLifetimeIHostApplicationLifetime interface

IHostApplicationLifetime permite actividades posteriores al inicio y apagado.IHostApplicationLifetime allows for post-startup and shutdown activities. Hay tres propiedades en la interfaz que son tokens de cancelación usados para registrar métodos Action que definen los eventos de inicio y apagado.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelaciónCancellation Token Se desencadena cuando…Triggered when…
ApplicationStarted El host se ha iniciado completamente.The host has fully started.
ApplicationStopped El host está completando un apagado estable.The host is completing a graceful shutdown. Deben procesarse todas las solicitudes.All requests should be processed. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.
ApplicationStopping El host está realizando un apagado estable.The host is performing a graceful shutdown. Puede que todavía se estén procesando las solicitudes.Requests may still be processing. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.
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.StopApplication requests termination of the app. La siguiente clase usa StopApplication para cerrar de forma estable una aplicación cuando se llama al método Shutdown de esa clase:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

Interfaz IApplicationLifetimeIApplicationLifetime interface

IApplicationLifetime permite actividades posteriores al inicio y apagado.IApplicationLifetime allows for post-startup and shutdown activities. Hay tres propiedades en la interfaz que son tokens de cancelación usados para registrar métodos Action que definen los eventos de inicio y apagado.Three properties on the interface are cancellation tokens used to register Action methods that define startup and shutdown events.

Token de cancelaciónCancellation Token Se desencadena cuando…Triggered when…
ApplicationStartedApplicationStarted El host se ha iniciado completamente.The host has fully started.
ApplicationStoppedApplicationStopped El host está completando un apagado estable.The host is completing a graceful shutdown. Deben procesarse todas las solicitudes.All requests should be processed. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.
ApplicationStoppingApplicationStopping El host está realizando un apagado estable.The host is performing a graceful shutdown. Puede que todavía se estén procesando las solicitudes.Requests may still be processing. El apagado se bloquea hasta que se complete este evento.Shutdown blocks until this event completes.
public class Startup
{
    public void Configure(IApplicationBuilder app, IApplicationLifetime 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.StopApplication requests termination of the app. La siguiente clase usa StopApplication para cerrar de forma estable una aplicación cuando se llama al método Shutdown de esa clase:The following class uses StopApplication to gracefully shut down an app when the class's Shutdown method is called:

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

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

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

Validación del ámbitoScope validation

CreateDefaultBuilder establece ServiceProviderOptions.ValidateScopes en true si el entorno de la aplicación es desarrollo.CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true if the app's environment is Development.

Cuando ValidateScopes está establecido en true, el proveedor de servicios predeterminado realiza comprobaciones para confirmar lo siguiente:When ValidateScopes is set to true, the default service provider performs checks to verify that:

  • Los servicios con ámbito no se resuelven directa o indirectamente desde el proveedor de servicios raíz.Scoped services aren't directly or indirectly resolved from the root service provider.
  • Los servicios con ámbito no se insertan directa o indirectamente en singletons.Scoped services aren't directly or indirectly injected into singletons.

El proveedor de servicios raíz se crea cuando se llama a BuildServiceProvider.The root service provider is created when BuildServiceProvider is called. 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.The root service provider's lifetime corresponds to the app/server's lifetime when the provider starts with the app and is disposed when the app shuts down.

De la eliminación de los servicios con ámbito se encarga el contenedor que los creó.Scoped services are disposed by the container that created them. 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.If a scoped service is created in the root container, the service's lifetime is effectively promoted to singleton because it's only disposed by the root container when app/server is shut down. Al validar los ámbitos de servicio, este tipo de situaciones se detectan cuando se llama a BuildServiceProvider.Validating service scopes catches these situations when BuildServiceProvider is called.

Para validar los ámbitos siempre, incluso en el entorno de producción, configure ServiceProviderOptions con UseDefaultServiceProvider en el generador de hosts:To always validate scopes, including in the Production environment, configure the ServiceProviderOptions with UseDefaultServiceProvider on the host builder:

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

Recursos adicionalesAdditional resources