ASP.NET Core Web Host
Note
This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 8 version of this article.
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. At a minimum, the host configures a server and a request processing pipeline. The host can also set up logging, dependency injection, and configuration.
This article covers the Web Host, which remains available only for backward compatibility. The ASP.NET Core templates create a WebApplicationBuilder and WebApplication, which is recommended for web apps. For more information on WebApplicationBuilder
and WebApplication
, see Migrate from ASP.NET Core 5.0 to 6.0
Set up a host
Create a host using an instance of IWebHostBuilder. This is typically performed in the app's entry point, the Main
method in Program.cs
. 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>();
}
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. This separation is required if you use Entity Framework Core tools. The tools expect to find a CreateWebHostBuilder
method that they can call at design time to configure the host without running the app. An alternative is to implement IDesignTimeDbContextFactory
. For more information, see Design-time DbContext Creation.
CreateDefaultBuilder
performs the following tasks:
- Configures Kestrel server as the web server using the app's hosting configuration providers. For the Kestrel server's default options, see Configure options for the ASP.NET Core Kestrel web server.
- Sets the content root to the path returned by Directory.GetCurrentDirectory.
- Loads host configuration from:
- Environment variables prefixed with
ASPNETCORE_
(for example,ASPNETCORE_ENVIRONMENT
). - Command-line arguments.
- Environment variables prefixed with
- Loads app configuration in the following order from:
appsettings.json
.appsettings.{Environment}.json
.- User secrets when the app runs in the
Development
environment using the entry assembly. - Environment variables.
- Command-line arguments.
- Configures logging for console and debug output. Logging includes log filtering rules specified in a Logging configuration section of an
appsettings.json
orappsettings.{Environment}.json
file. - When running behind IIS with the ASP.NET Core Module,
CreateDefaultBuilder
enables IIS Integration, which configures the app's base address and port. IIS Integration also configures the app to capture startup errors. For the IIS default options, see Host ASP.NET Core on Windows with IIS. - Sets ServiceProviderOptions.ValidateScopes to
true
if the app's environment is Development. For more information, see Scope validation.
The configuration defined by CreateDefaultBuilder
can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. A few examples follow:
ConfigureAppConfiguration is used to specify additional
IConfiguration
for the app. The followingConfigureAppConfiguration
call adds a delegate to include app configuration in theappsettings.xml
file.ConfigureAppConfiguration
may be called multiple times. Note that this configuration doesn't apply to the host (for example, server URLs or environment). See the Host configuration values section.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
The following
ConfigureLogging
call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. This setting overrides the settings inappsettings.Development.json
(LogLevel.Debug
) andappsettings.Production.json
(LogLevel.Error
) configured byCreateDefaultBuilder
.ConfigureLogging
may be called multiple times.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
The following call to
ConfigureKestrel
overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured byCreateDefaultBuilder
:WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
The content root determines where the host searches for content files, such as MVC view files. When the app is started from the project's root folder, the project's root folder is used as the content root. This is the default used in Visual Studio and the dotnet new templates.
For more information on app configuration, see Configuration in ASP.NET Core.
Note
As an alternative to using the static CreateDefaultBuilder
method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.
When setting up a host, Configure and ConfigureServices methods can be provided. If a Startup
class is specified, it must define a Configure
method. For more information, see App startup in ASP.NET Core. Multiple calls to ConfigureServices
append to one another. Multiple calls to Configure
or UseStartup
on the WebHostBuilder
replace previous settings.
Host configuration values
WebHostBuilder relies on the following approaches to set the host configuration values:
- Host builder configuration, which includes environment variables with the format
ASPNETCORE_{configurationKey}
. For example,ASPNETCORE_ENVIRONMENT
. - Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
- UseSetting and the associated key. When setting a value with
UseSetting
, the value is set as a string regardless of the type.
The host uses whichever option sets a value last. For more information, see Override configuration in the next section.
Application Key (Name)
The IWebHostEnvironment.ApplicationName
property is automatically set when UseStartup or Configure is called during host construction. The value is set to the name of the assembly containing the app's entry point. To set the value explicitly, use the WebHostDefaults.ApplicationKey:
Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: UseSetting
Environment variable: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Capture Startup Errors
This setting controls the capture of startup errors.
Key: captureStartupErrors
Type: bool (true
or 1
)
Default: Defaults to false
unless the app runs with Kestrel behind IIS, where the default is true
.
Set using: CaptureStartupErrors
Environment variable: ASPNETCORE_CAPTURESTARTUPERRORS
When false
, errors during startup result in the host exiting. When true
, the host captures exceptions during startup and attempts to start the server.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Content root
This setting determines where ASP.NET Core begins searching for content files.
Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: ASPNETCORE_CONTENTROOT
The content root is also used as the base path for the web root. If the content root path doesn't exist, the host fails to start.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
For more information, see:
Detailed Errors
Determines if detailed errors should be captured.
Key: detailedErrors
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_DETAILEDERRORS
When enabled (or when the Environment is set to Development
), the app captures detailed exceptions.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Environment
Sets the app's environment.
Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: ASPNETCORE_ENVIRONMENT
The environment can be set to any value. Framework-defined values include Development
, Staging
, and Production
. Values aren't case sensitive. By default, the Environment is read from the ASPNETCORE_ENVIRONMENT
environment variable. When using Visual Studio, environment variables may be set in the launchSettings.json
file. For more information, see Use multiple environments in ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hosting Startup Assemblies
Sets the app's hosting startup assemblies.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
A semicolon-delimited string of hosting startup assemblies to load on startup.
Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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")
HTTPS Port
Set the HTTPS port to redirect to if you get a non-HTTPS connection. Used in enforcing HTTPS. This setting doesn't cause the server to listen on the specified port. That is, it's possible to accidentally redirect requests to an unused port.
Key: https_port
Type: string
Default: A default value isn't set.
Set using: UseSetting
Environment variable: ASPNETCORE_HTTPS_PORT
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
HTTPS Ports
Set the ports to listen on for HTTPS connections.
Key: https_ports
Type: string
Default: A default value isn't set.
Set using: UseSetting
Environment variable: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_ports", "8080")
Hosting Startup Exclude Assemblies
A semicolon-delimited string of hosting startup assemblies to exclude on startup.
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Prefer Hosting URLs
Indicates whether the host should listen on the URLs configured with the WebHostBuilder
instead of those configured with the IServer
implementation.
Key: preferHostingUrls
Type: bool (true
or 1
)
Default: false
Set using: PreferHostingUrls
Environment variable: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Prevent Hosting Startup
Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. For more information, see Use hosting startup assemblies in ASP.NET Core.
Key: preventHostingStartup
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Server URLs
Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.
Key: urls
Type: string
Default: http://localhost:5000
Set using: UseUrls
Environment variable: ASPNETCORE_URLS
Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. For example, http://localhost:123
. 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
). The protocol (http://
or https://
) must be included with each URL. Supported formats vary among servers.
WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Kestrel has its own endpoint configuration API. For more information, see Configure endpoints for the ASP.NET Core Kestrel web server.
Shutdown Timeout
Specifies the amount of time to wait for Web Host to shut down.
Key: shutdownTimeoutSeconds
Type: int
Default: 5
Set using: UseShutdownTimeout
Environment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Although the key accepts an int with UseSetting
(for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), the UseShutdownTimeout extension method takes a TimeSpan.
During the timeout period, hosting:
- Triggers IApplicationLifetime.ApplicationStopping.
- Attempts to stop hosted services, logging any errors for services that fail to stop.
If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. The services stop even if they haven't finished processing. If services require additional time to stop, increase the timeout.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Startup Assembly
Determines the assembly to search for the Startup
class.
Key: startupAssembly
Type: string
Default: The app's assembly
Set using: UseStartup
Environment variable: ASPNETCORE_STARTUPASSEMBLY
The assembly by name (string
) or type (TStartup
) can be referenced. If multiple UseStartup
methods are called, the last one takes precedence.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Web root
Sets the relative path to the app's static assets.
Key: webroot
Type: string
Default: The default is wwwroot
. The path to {content root}/wwwroot must exist. If the path doesn't exist, a no-op file provider is used.
Set using: UseWebRoot
Environment variable: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
For more information, see:
Override configuration
Use Configuration to configure Web Host. In the following example, host configuration is optionally specified in a hostsettings.json
file. Any configuration loaded from the hostsettings.json
file may be overridden by command-line arguments. The built configuration (in config
) is used to configure the host with UseConfiguration. IWebHostBuilder
configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration
doesn't affect the IWebHostBuilder
configuration.
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
:
{
urls: "http://*:5005"
}
Note
UseConfiguration only copies keys from the provided IConfiguration
to the host builder configuration. Therefore, setting reloadOnChange: true
for JSON, INI, and XML settings files has no effect.
To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. 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"
Manage the host
Run
The Run
method starts the web app and blocks the calling thread until the host is shut down:
host.Run();
Start
Run the host in a non-blocking manner by calling its Start
method:
using (host)
{
host.Start();
Console.ReadLine();
}
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();
}
The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder
using a static convenience method. These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):
Start(RequestDelegate app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, RequestDelegate app)
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();
}
Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080
.
Start(Action<IRouteBuilder> routeBuilder)
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();
}
Use the following browser requests with the example:
Request | Response |
---|---|
http://localhost:5000/hello/Martin |
Hello, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Throws an exception with string "ooops!" |
http://localhost:5000/throw |
Throws an exception with string "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, Action<IRouteBuilder> routeBuilder)
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();
}
Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
StartWith(string url, Action<IApplicationBuilder> app)
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();
}
Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080
.
IWebHostEnvironment interface
The IWebHostEnvironment
interface provides information about the app's web hosting environment. 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
}
}
A convention-based approach can be used to configure the app at startup based on the environment. 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;
}
}
Note
In addition to the IsDevelopment
extension method, IWebHostEnvironment
offers IsStaging
, IsProduction
, and IsEnvironment(string environmentName)
methods. For more information, see Use multiple environments in ASP.NET Core.
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
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;
}
IHostApplicationLifetime interface
IHostApplicationLifetime
allows for post-startup and shutdown activities. Three properties on the interface are cancellation tokens used to register Action
methods that define startup and shutdown events.
Cancellation Token | Triggered when… |
---|---|
ApplicationStarted |
The host has fully started. |
ApplicationStopped |
The host is completing a graceful shutdown. All requests should be processed. Shutdown blocks until this event completes. |
ApplicationStopping |
The host is performing a graceful shutdown. Requests may still be processing. 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
requests termination of the app. 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();
}
}
Scope validation
CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true
if the app's environment is Development.
When ValidateScopes
is set to true
, the default service provider performs checks to verify that:
- Scoped services aren't directly or indirectly resolved from the root service provider.
- Scoped services aren't directly or indirectly injected into singletons.
The root service provider is created when BuildServiceProvider is called. 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.
Scoped services are disposed by the container that created them. 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. Validating service scopes catches these situations when BuildServiceProvider
is called.
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;
})
Additional resources
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. At a minimum, the host configures a server and a request processing pipeline. The host can also set up logging, dependency injection, and configuration.
This article covers the Web Host, which remains available only for backward compatibility. The ASP.NET Core templates create a .NET Generic Host, which is recommended for all app types.
Set up a host
Create a host using an instance of IWebHostBuilder. This is typically performed in the app's entry point, the Main
method.
In the project templates, Main
is located in Program.cs
. 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>();
}
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. This separation is required if you use Entity Framework Core tools. The tools expect to find a CreateWebHostBuilder
method that they can call at design time to configure the host without running the app. An alternative is to implement IDesignTimeDbContextFactory
. For more information, see Design-time DbContext Creation.
CreateDefaultBuilder
performs the following tasks:
- Configures Kestrel server as the web server using the app's hosting configuration providers. For the Kestrel server's default options, see Configure options for the ASP.NET Core Kestrel web server.
- Sets the content root to the path returned by Directory.GetCurrentDirectory.
- Loads host configuration from:
- Environment variables prefixed with
ASPNETCORE_
(for example,ASPNETCORE_ENVIRONMENT
). - Command-line arguments.
- Environment variables prefixed with
- Loads app configuration in the following order from:
appsettings.json
.appsettings.{Environment}.json
.- User secrets when the app runs in the
Development
environment using the entry assembly. - Environment variables.
- Command-line arguments.
- Configures logging for console and debug output. Logging includes log filtering rules specified in a Logging configuration section of an
appsettings.json
orappsettings.{Environment}.json
file. - When running behind IIS with the ASP.NET Core Module,
CreateDefaultBuilder
enables IIS Integration, which configures the app's base address and port. IIS Integration also configures the app to capture startup errors. For the IIS default options, see Host ASP.NET Core on Windows with IIS. - Sets ServiceProviderOptions.ValidateScopes to
true
if the app's environment is Development. For more information, see Scope validation.
The configuration defined by CreateDefaultBuilder
can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. A few examples follow:
ConfigureAppConfiguration is used to specify additional
IConfiguration
for the app. The followingConfigureAppConfiguration
call adds a delegate to include app configuration in theappsettings.xml
file.ConfigureAppConfiguration
may be called multiple times. Note that this configuration doesn't apply to the host (for example, server URLs or environment). See the Host configuration values section.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
The following
ConfigureLogging
call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. This setting overrides the settings inappsettings.Development.json
(LogLevel.Debug
) andappsettings.Production.json
(LogLevel.Error
) configured byCreateDefaultBuilder
.ConfigureLogging
may be called multiple times.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
The following call to
ConfigureKestrel
overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured byCreateDefaultBuilder
:WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
The content root determines where the host searches for content files, such as MVC view files. When the app is started from the project's root folder, the project's root folder is used as the content root. This is the default used in Visual Studio and the dotnet new templates.
For more information on app configuration, see Configuration in ASP.NET Core.
Note
As an alternative to using the static CreateDefaultBuilder
method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.
When setting up a host, Configure and ConfigureServices methods can be provided. If a Startup
class is specified, it must define a Configure
method. For more information, see App startup in ASP.NET Core. Multiple calls to ConfigureServices
append to one another. Multiple calls to Configure
or UseStartup
on the WebHostBuilder
replace previous settings.
Host configuration values
WebHostBuilder relies on the following approaches to set the host configuration values:
- Host builder configuration, which includes environment variables with the format
ASPNETCORE_{configurationKey}
. For example,ASPNETCORE_ENVIRONMENT
. - Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
- UseSetting and the associated key. When setting a value with
UseSetting
, the value is set as a string regardless of the type.
The host uses whichever option sets a value last. For more information, see Override configuration in the next section.
Application Key (Name)
The IWebHostEnvironment.ApplicationName
property is automatically set when UseStartup or Configure is called during host construction. The value is set to the name of the assembly containing the app's entry point. To set the value explicitly, use the WebHostDefaults.ApplicationKey:
Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: UseSetting
Environment variable: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Capture Startup Errors
This setting controls the capture of startup errors.
Key: captureStartupErrors
Type: bool (true
or 1
)
Default: Defaults to false
unless the app runs with Kestrel behind IIS, where the default is true
.
Set using: CaptureStartupErrors
Environment variable: ASPNETCORE_CAPTURESTARTUPERRORS
When false
, errors during startup result in the host exiting. When true
, the host captures exceptions during startup and attempts to start the server.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Content root
This setting determines where ASP.NET Core begins searching for content files.
Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: ASPNETCORE_CONTENTROOT
The content root is also used as the base path for the web root. If the content root path doesn't exist, the host fails to start.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
For more information, see:
Detailed Errors
Determines if detailed errors should be captured.
Key: detailedErrors
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_DETAILEDERRORS
When enabled (or when the Environment is set to Development
), the app captures detailed exceptions.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Environment
Sets the app's environment.
Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: ASPNETCORE_ENVIRONMENT
The environment can be set to any value. Framework-defined values include Development
, Staging
, and Production
. Values aren't case sensitive. By default, the Environment is read from the ASPNETCORE_ENVIRONMENT
environment variable. When using Visual Studio, environment variables may be set in the launchSettings.json
file. For more information, see Use multiple environments in ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hosting Startup Assemblies
Sets the app's hosting startup assemblies.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
A semicolon-delimited string of hosting startup assemblies to load on startup.
Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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")
HTTPS Port
Set the HTTPS redirect port. Used in enforcing HTTPS.
Key: https_port
Type: string
Default: A default value isn't set.
Set using: UseSetting
Environment variable: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
Hosting Startup Exclude Assemblies
A semicolon-delimited string of hosting startup assemblies to exclude on startup.
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Prefer Hosting URLs
Indicates whether the host should listen on the URLs configured with the WebHostBuilder
instead of those configured with the IServer
implementation.
Key: preferHostingUrls
Type: bool (true
or 1
)
Default: false
Set using: PreferHostingUrls
Environment variable: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Prevent Hosting Startup
Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. For more information, see Use hosting startup assemblies in ASP.NET Core.
Key: preventHostingStartup
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Server URLs
Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.
Key: urls
Type: string
Default: http://localhost:5000
Set using: UseUrls
Environment variable: ASPNETCORE_URLS
Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. For example, http://localhost:123
. 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
). The protocol (http://
or https://
) must be included with each URL. Supported formats vary among servers.
WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Kestrel has its own endpoint configuration API. For more information, see Configure endpoints for the ASP.NET Core Kestrel web server.
Shutdown Timeout
Specifies the amount of time to wait for Web Host to shut down.
Key: shutdownTimeoutSeconds
Type: int
Default: 5
Set using: UseShutdownTimeout
Environment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Although the key accepts an int with UseSetting
(for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), the UseShutdownTimeout extension method takes a TimeSpan.
During the timeout period, hosting:
- Triggers IApplicationLifetime.ApplicationStopping.
- Attempts to stop hosted services, logging any errors for services that fail to stop.
If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. The services stop even if they haven't finished processing. If services require additional time to stop, increase the timeout.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Startup Assembly
Determines the assembly to search for the Startup
class.
Key: startupAssembly
Type: string
Default: The app's assembly
Set using: UseStartup
Environment variable: ASPNETCORE_STARTUPASSEMBLY
The assembly by name (string
) or type (TStartup
) can be referenced. If multiple UseStartup
methods are called, the last one takes precedence.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Web root
Sets the relative path to the app's static assets.
Key: webroot
Type: string
Default: The default is wwwroot
. The path to {content root}/wwwroot must exist. If the path doesn't exist, a no-op file provider is used.
Set using: UseWebRoot
Environment variable: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
For more information, see:
Override configuration
Use Configuration to configure Web Host. In the following example, host configuration is optionally specified in a hostsettings.json
file. Any configuration loaded from the hostsettings.json
file may be overridden by command-line arguments. The built configuration (in config
) is used to configure the host with UseConfiguration. IWebHostBuilder
configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration
doesn't affect the IWebHostBuilder
configuration.
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
:
{
urls: "http://*:5005"
}
Note
UseConfiguration only copies keys from the provided IConfiguration
to the host builder configuration. Therefore, setting reloadOnChange: true
for JSON, INI, and XML settings files has no effect.
To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. 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"
Manage the host
Run
The Run
method starts the web app and blocks the calling thread until the host is shut down:
host.Run();
Start
Run the host in a non-blocking manner by calling its Start
method:
using (host)
{
host.Start();
Console.ReadLine();
}
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();
}
The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder
using a static convenience method. These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):
Start(RequestDelegate app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, RequestDelegate app)
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();
}
Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080
.
Start(Action<IRouteBuilder> routeBuilder)
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();
}
Use the following browser requests with the example:
Request | Response |
---|---|
http://localhost:5000/hello/Martin |
Hello, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Throws an exception with string "ooops!" |
http://localhost:5000/throw |
Throws an exception with string "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, Action<IRouteBuilder> routeBuilder)
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();
}
Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
StartWith(string url, Action<IApplicationBuilder> app)
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();
}
Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080
.
IWebHostEnvironment interface
The IWebHostEnvironment
interface provides information about the app's web hosting environment. 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
}
}
A convention-based approach can be used to configure the app at startup based on the environment. 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;
}
}
Note
In addition to the IsDevelopment
extension method, IWebHostEnvironment
offers IsStaging
, IsProduction
, and IsEnvironment(string environmentName)
methods. For more information, see Use multiple environments in ASP.NET Core.
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
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;
}
IHostApplicationLifetime interface
IHostApplicationLifetime
allows for post-startup and shutdown activities. Three properties on the interface are cancellation tokens used to register Action
methods that define startup and shutdown events.
Cancellation Token | Triggered when… |
---|---|
ApplicationStarted |
The host has fully started. |
ApplicationStopped |
The host is completing a graceful shutdown. All requests should be processed. Shutdown blocks until this event completes. |
ApplicationStopping |
The host is performing a graceful shutdown. Requests may still be processing. 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
requests termination of the app. 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();
}
}
Scope validation
CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true
if the app's environment is Development.
When ValidateScopes
is set to true
, the default service provider performs checks to verify that:
- Scoped services aren't directly or indirectly resolved from the root service provider.
- Scoped services aren't directly or indirectly injected into singletons.
The root service provider is created when BuildServiceProvider is called. 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.
Scoped services are disposed by the container that created them. 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. Validating service scopes catches these situations when BuildServiceProvider
is called.
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;
})
Additional resources
ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management. At a minimum, the host configures a server and a request processing pipeline. The host can also set up logging, dependency injection, and configuration.
This article covers the Web Host, which remains available only for backward compatibility. The ASP.NET Core templates create a .NET Generic Host, which is recommended for all app types.
Set up a host
Create a host using an instance of IWebHostBuilder. This is typically performed in the app's entry point, the Main
method.
In the project templates, Main
is located in Program.cs
. 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>();
}
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. This separation is required if you use Entity Framework Core tools. The tools expect to find a CreateWebHostBuilder
method that they can call at design time to configure the host without running the app. An alternative is to implement IDesignTimeDbContextFactory
. For more information, see Design-time DbContext Creation.
CreateDefaultBuilder
performs the following tasks:
- Configures Kestrel server as the web server using the app's hosting configuration providers. For the Kestrel server's default options, see Kestrel web server in ASP.NET Core.
- Sets the content root to the path returned by Directory.GetCurrentDirectory.
- Loads host configuration from:
- Environment variables prefixed with
ASPNETCORE_
(for example,ASPNETCORE_ENVIRONMENT
). - Command-line arguments.
- Environment variables prefixed with
- Loads app configuration in the following order from:
appsettings.json
.appsettings.{Environment}.json
.- User secrets when the app runs in the
Development
environment using the entry assembly. - Environment variables.
- Command-line arguments.
- Configures logging for console and debug output. Logging includes log filtering rules specified in a Logging configuration section of an
appsettings.json
orappsettings.{Environment}.json
file. - When running behind IIS with the ASP.NET Core Module,
CreateDefaultBuilder
enables IIS Integration, which configures the app's base address and port. IIS Integration also configures the app to capture startup errors. For the IIS default options, see Host ASP.NET Core on Windows with IIS. - Sets ServiceProviderOptions.ValidateScopes to
true
if the app's environment is Development. For more information, see Scope validation.
The configuration defined by CreateDefaultBuilder
can be overridden and augmented by ConfigureAppConfiguration, ConfigureLogging, and other methods and extension methods of IWebHostBuilder. A few examples follow:
ConfigureAppConfiguration is used to specify additional
IConfiguration
for the app. The followingConfigureAppConfiguration
call adds a delegate to include app configuration in theappsettings.xml
file.ConfigureAppConfiguration
may be called multiple times. Note that this configuration doesn't apply to the host (for example, server URLs or environment). See the Host configuration values section.WebHost.CreateDefaultBuilder(args) .ConfigureAppConfiguration((hostingContext, config) => { config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true); }) ...
The following
ConfigureLogging
call adds a delegate to configure the minimum logging level (SetMinimumLevel) to LogLevel.Warning. This setting overrides the settings inappsettings.Development.json
(LogLevel.Debug
) andappsettings.Production.json
(LogLevel.Error
) configured byCreateDefaultBuilder
.ConfigureLogging
may be called multiple times.WebHost.CreateDefaultBuilder(args) .ConfigureLogging(logging => { logging.SetMinimumLevel(LogLevel.Warning); }) ...
The following call to
ConfigureKestrel
overrides the default Limits.MaxRequestBodySize of 30,000,000 bytes established when Kestrel was configured byCreateDefaultBuilder
:WebHost.CreateDefaultBuilder(args) .ConfigureKestrel((context, options) => { options.Limits.MaxRequestBodySize = 20000000; });
The content root determines where the host searches for content files, such as MVC view files. When the app is started from the project's root folder, the project's root folder is used as the content root. This is the default used in Visual Studio and the dotnet new templates.
For more information on app configuration, see Configuration in ASP.NET Core.
Note
As an alternative to using the static CreateDefaultBuilder
method, creating a host from WebHostBuilder is a supported approach with ASP.NET Core 2.x.
When setting up a host, Configure and ConfigureServices methods can be provided. If a Startup
class is specified, it must define a Configure
method. For more information, see App startup in ASP.NET Core. Multiple calls to ConfigureServices
append to one another. Multiple calls to Configure
or UseStartup
on the WebHostBuilder
replace previous settings.
Host configuration values
WebHostBuilder relies on the following approaches to set the host configuration values:
- Host builder configuration, which includes environment variables with the format
ASPNETCORE_{configurationKey}
. For example,ASPNETCORE_ENVIRONMENT
. - Extensions such as UseContentRoot and UseConfiguration (see the Override configuration section).
- UseSetting and the associated key. When setting a value with
UseSetting
, the value is set as a string regardless of the type.
The host uses whichever option sets a value last. For more information, see Override configuration in the next section.
Application Key (Name)
The IWebHostEnvironment.ApplicationName
property is automatically set when UseStartup or Configure is called during host construction. The value is set to the name of the assembly containing the app's entry point. To set the value explicitly, use the WebHostDefaults.ApplicationKey:
Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: UseSetting
Environment variable: ASPNETCORE_APPLICATIONNAME
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")
Capture Startup Errors
This setting controls the capture of startup errors.
Key: captureStartupErrors
Type: bool (true
or 1
)
Default: Defaults to false
unless the app runs with Kestrel behind IIS, where the default is true
.
Set using: CaptureStartupErrors
Environment variable: ASPNETCORE_CAPTURESTARTUPERRORS
When false
, errors during startup result in the host exiting. When true
, the host captures exceptions during startup and attempts to start the server.
WebHost.CreateDefaultBuilder(args)
.CaptureStartupErrors(true)
Content root
This setting determines where ASP.NET Core begins searching for content files.
Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: ASPNETCORE_CONTENTROOT
The content root is also used as the base path for the web root. If the content root path doesn't exist, the host fails to start.
WebHost.CreateDefaultBuilder(args)
.UseContentRoot("c:\\<content-root>")
For more information, see:
Detailed Errors
Determines if detailed errors should be captured.
Key: detailedErrors
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_DETAILEDERRORS
When enabled (or when the Environment is set to Development
), the app captures detailed exceptions.
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.DetailedErrorsKey, "true")
Environment
Sets the app's environment.
Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: ASPNETCORE_ENVIRONMENT
The environment can be set to any value. Framework-defined values include Development
, Staging
, and Production
. Values aren't case sensitive. By default, the Environment is read from the ASPNETCORE_ENVIRONMENT
environment variable. When using Visual Studio, environment variables may be set in the launchSettings.json
file. For more information, see Use multiple environments in ASP.NET Core.
WebHost.CreateDefaultBuilder(args)
.UseEnvironment(EnvironmentName.Development)
Hosting Startup Assemblies
Sets the app's hosting startup assemblies.
Key: hostingStartupAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES
A semicolon-delimited string of hosting startup assemblies to load on startup.
Although the configuration value defaults to an empty string, the hosting startup assemblies always include the app's assembly. 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")
HTTPS Port
Set the HTTPS redirect port. Used in enforcing HTTPS.
Key: https_port
Type: string
Default: A default value isn't set.
Set using: UseSetting
Environment variable: ASPNETCORE_HTTPS_PORTS
WebHost.CreateDefaultBuilder(args)
.UseSetting("https_port", "8080")
Hosting Startup Exclude Assemblies
A semicolon-delimited string of hosting startup assemblies to exclude on startup.
Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Set using: UseSetting
Environment variable: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")
Prefer Hosting URLs
Indicates whether the host should listen on the URLs configured with the WebHostBuilder
instead of those configured with the IServer
implementation.
Key: preferHostingUrls
Type: bool (true
or 1
)
Default: false
Set using: PreferHostingUrls
Environment variable: ASPNETCORE_PREFERHOSTINGURLS
WebHost.CreateDefaultBuilder(args)
.PreferHostingUrls(true)
Prevent Hosting Startup
Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. For more information, see Use hosting startup assemblies in ASP.NET Core.
Key: preventHostingStartup
Type: bool (true
or 1
)
Default: false
Set using: UseSetting
Environment variable: ASPNETCORE_PREVENTHOSTINGSTARTUP
WebHost.CreateDefaultBuilder(args)
.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")
Server URLs
Indicates the IP addresses or host addresses with ports and protocols that the server should listen on for requests.
Key: urls
Type: string
Default: http://localhost:5000
Set using: UseUrls
Environment variable: ASPNETCORE_URLS
Set to a semicolon-separated (;) list of URL prefixes to which the server should respond. For example, http://localhost:123
. 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
). The protocol (http://
or https://
) must be included with each URL. Supported formats vary among servers.
WebHost.CreateDefaultBuilder(args)
.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002")
Kestrel has its own endpoint configuration API. For more information, see Kestrel web server in ASP.NET Core.
Shutdown Timeout
Specifies the amount of time to wait for Web Host to shut down.
Key: shutdownTimeoutSeconds
Type: int
Default: 5
Set using: UseShutdownTimeout
Environment variable: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS
Although the key accepts an int with UseSetting
(for example, .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")
), the UseShutdownTimeout extension method takes a TimeSpan.
During the timeout period, hosting:
- Triggers IApplicationLifetime.ApplicationStopping.
- Attempts to stop hosted services, logging any errors for services that fail to stop.
If the timeout period expires before all of the hosted services stop, any remaining active services are stopped when the app shuts down. The services stop even if they haven't finished processing. If services require additional time to stop, increase the timeout.
WebHost.CreateDefaultBuilder(args)
.UseShutdownTimeout(TimeSpan.FromSeconds(10))
Startup Assembly
Determines the assembly to search for the Startup
class.
Key: startupAssembly
Type: string
Default: The app's assembly
Set using: UseStartup
Environment variable: ASPNETCORE_STARTUPASSEMBLY
The assembly by name (string
) or type (TStartup
) can be referenced. If multiple UseStartup
methods are called, the last one takes precedence.
WebHost.CreateDefaultBuilder(args)
.UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
.UseStartup<TStartup>()
Web root
Sets the relative path to the app's static assets.
Key: webroot
Type: string
Default: The default is wwwroot
. The path to {content root}/wwwroot must exist. If the path doesn't exist, a no-op file provider is used.
Set using: UseWebRoot
Environment variable: ASPNETCORE_WEBROOT
WebHost.CreateDefaultBuilder(args)
.UseWebRoot("public")
For more information, see:
Override configuration
Use Configuration to configure Web Host. In the following example, host configuration is optionally specified in a hostsettings.json
file. Any configuration loaded from the hostsettings.json
file may be overridden by command-line arguments. The built configuration (in config
) is used to configure the host with UseConfiguration. IWebHostBuilder
configuration is added to the app's configuration, but the converse isn't true—ConfigureAppConfiguration
doesn't affect the IWebHostBuilder
configuration.
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
:
{
urls: "http://*:5005"
}
Note
UseConfiguration only copies keys from the provided IConfiguration
to the host builder configuration. Therefore, setting reloadOnChange: true
for JSON, INI, and XML settings files has no effect.
To specify the host run on a particular URL, the desired value can be passed in from a command prompt when executing dotnet run. 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"
Manage the host
Run
The Run
method starts the web app and blocks the calling thread until the host is shut down:
host.Run();
Start
Run the host in a non-blocking manner by calling its Start
method:
using (host)
{
host.Start();
Console.ReadLine();
}
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();
}
The app can initialize and start a new host using the pre-configured defaults of CreateDefaultBuilder
using a static convenience method. These methods start the server without console output and with WaitForShutdown wait for a break (Ctrl-C/SIGINT or SIGTERM):
Start(RequestDelegate app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, RequestDelegate app)
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();
}
Produces the same result as Start(RequestDelegate app), except the app responds on http://localhost:8080
.
Start(Action<IRouteBuilder> routeBuilder)
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();
}
Use the following browser requests with the example:
Request | Response |
---|---|
http://localhost:5000/hello/Martin |
Hello, Martin! |
http://localhost:5000/buenosdias/Catrina |
Buenos dias, Catrina! |
http://localhost:5000/throw/ooops! |
Throws an exception with string "ooops!" |
http://localhost:5000/throw |
Throws an exception with string "Uh oh!" |
http://localhost:5000/Sante/Kevin |
Sante, Kevin! |
http://localhost:5000 |
Hello World! |
WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
Start(string url, Action<IRouteBuilder> routeBuilder)
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();
}
Produces the same result as Start(Action<IRouteBuilder> routeBuilder), except the app responds at http://localhost:8080
.
StartWith(Action<IApplicationBuilder> app)
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();
}
Make a request in the browser to http://localhost:5000
to receive the response "Hello World!" WaitForShutdown
blocks until a break (Ctrl-C/SIGINT or SIGTERM) is issued. The app displays the Console.WriteLine
message and waits for a keypress to exit.
StartWith(string url, Action<IApplicationBuilder> app)
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();
}
Produces the same result as StartWith(Action<IApplicationBuilder> app), except the app responds on http://localhost:8080
.
IWebHostEnvironment interface
The IWebHostEnvironment
interface provides information about the app's web hosting environment. 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
}
}
A convention-based approach can be used to configure the app at startup based on the environment. 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;
}
}
Note
In addition to the IsDevelopment
extension method, IWebHostEnvironment
offers IsStaging
, IsProduction
, and IsEnvironment(string environmentName)
methods. For more information, see Use multiple environments in ASP.NET Core.
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
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;
}
IHostApplicationLifetime interface
IHostApplicationLifetime
allows for post-startup and shutdown activities. Three properties on the interface are cancellation tokens used to register Action
methods that define startup and shutdown events.
Cancellation Token | Triggered when… |
---|---|
ApplicationStarted |
The host has fully started. |
ApplicationStopped |
The host is completing a graceful shutdown. All requests should be processed. Shutdown blocks until this event completes. |
ApplicationStopping |
The host is performing a graceful shutdown. Requests may still be processing. 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
requests termination of the app. 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();
}
}
Scope validation
CreateDefaultBuilder sets ServiceProviderOptions.ValidateScopes to true
if the app's environment is Development.
When ValidateScopes
is set to true
, the default service provider performs checks to verify that:
- Scoped services aren't directly or indirectly resolved from the root service provider.
- Scoped services aren't directly or indirectly injected into singletons.
The root service provider is created when BuildServiceProvider is called. 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.
Scoped services are disposed by the container that created them. 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. Validating service scopes catches these situations when BuildServiceProvider
is called.
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;
})
Additional resources
ASP.NET Core