67 KiB

Raw Blame History

title

author

description

monikerRange

ms.author

ms.custom

ms.date

no-loc

uid

.NET Generic Host in ASP.NET Core

rick-anderson

Use .NET Core Generic Host in ASP.NET Core apps. Generic Host is responsible for app startup and lifetime management.

>= aspnetcore-2.1

riande

mvc

4/17/2020

Home

Privacy

Kestrel

appsettings.json

ASP.NET Core Identity

Blazor

Blazor Server

Blazor WebAssembly

Identity

Let's Encrypt

Razor

SignalR

fundamentals/host/generic-host

.NET Generic Host in ASP.NET Core

::: moniker range=">= aspnetcore-5.0"

The ASP.NET Core templates create a .NET Core Generic Host (xref:Microsoft.Extensions.Hosting.HostBuilder).

This topic provides information on using .NET Generic Host in ASP.NET Core. For information on using .NET Generic Host in console apps, see .NET Generic Host.

Host definition

A host is an object that encapsulates an app's resources, such as:

Dependency injection (DI)
Logging
Configuration
IHostedService implementations

When a host starts, it calls xref:Microsoft.Extensions.Hosting.IHostedService.StartAsync%2A?displayProperty=nameWithType on each implementation of xref:Microsoft.Extensions.Hosting.IHostedService registered in the service container's collection of hosted services. In a web app, one of the IHostedService implementations is a web service that starts an HTTP server implementation.

The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Set up a host

The host is typically configured, built, and run by code in the Program class. The Main method:

Calls a CreateHostBuilder method to create and configure a builder object.
Calls Build and Run methods on the builder object.

The ASP.NET Core web templates generate the following code to create a host:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

The following code creates a non-HTTP workload with an IHostedService implementation added to the DI container.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

For an HTTP workload, the Main method is the same but CreateHostBuilder calls ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

If the app uses Entity Framework Core, don't change the name or signature of the CreateHostBuilder method. The Entity Framework Core tools expect to find a CreateHostBuilder method that configures the host without running the app. For more information, see Design-time DbContext Creation.

Default builder settings

The xref:Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder* method:

Sets the content root to the path returned by xref:System.IO.Directory.GetCurrentDirectory*.
Loads host configuration from:
- Environment variables prefixed with DOTNET_.
- Command-line arguments.
Loads app configuration from:
- appsettings.json.
- appsettings.{Environment}.json.
- User secrets when the app runs in the Development environment.
- Environment variables.
- Command-line arguments.
Adds the following logging providers:
- Console
- Debug
- EventSource
- EventLog (only when running on Windows)
Enables scope validation and dependency validation when the environment is Development.

The xref:Microsoft.Extensions.Hosting.GenericHostBuilderExtensions.ConfigureWebHostDefaults* method:

Loads host configuration from environment variables prefixed with ASPNETCORE_.
Sets Kestrel server as the web server and configures it using the app's hosting configuration providers. For the Kestrel server's default options, see xref:fundamentals/servers/kestrel/options.
Adds Host Filtering middleware.
Adds Forwarded Headers middleware if ASPNETCORE_FORWARDEDHEADERS_ENABLED equals true.
Enables IIS integration. For the IIS default options, see xref:host-and-deploy/iis/index#iis-options.

The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

Framework-provided services

The following services are registered automatically:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

For more information on framework-provided services, see xref:fundamentals/dependency-injection#framework-provided-services.

IHostApplicationLifetime

Inject the xref:Microsoft.Extensions.Hosting.IHostApplicationLifetime (formerly IApplicationLifetime) service into any class to handle post-startup and graceful shutdown tasks. Three properties on the interface are cancellation tokens used to register app start and app stop event handler methods. The interface also includes a StopApplication method.

The following example is an IHostedService implementation that registers IHostApplicationLifetime events:

[!code-csharp]

IHostLifetime

The xref:Microsoft.Extensions.Hosting.IHostLifetime implementation controls when the host starts and when it stops. The last implementation registered is used.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:

Listens for Ctrl+C/SIGINT or SIGTERM and calls xref:Microsoft.Extensions.Hosting.IHostApplicationLifetime.StopApplication* to start the shutdown process.
Unblocks extensions such as RunAsync and WaitForShutdownAsync.

IHostEnvironment

Inject the xref:Microsoft.Extensions.Hosting.IHostEnvironment service into a class to get information about the following settings:

ApplicationName
EnvironmentName
ContentRootPath

Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds the WebRootPath.

Host configuration

Host configuration is used for the properties of the xref:Microsoft.Extensions.Hosting.IHostEnvironment implementation.

Host configuration is available from HostBuilderContext.Configuration inside xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureAppConfiguration*. After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

To add host configuration, call xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration* on IHostBuilder. ConfigureHostConfiguration can be called multiple times with additive results. The host uses whichever option sets a value last on a given key.

The environment variable provider with prefix DOTNET_ and command-line arguments are included by CreateDefaultBuilder. For web apps, the environment variable provider with prefix ASPNETCORE_ is added. The prefix is removed when the environment variables are read. For example, the environment variable value for ASPNETCORE_ENVIRONMENT becomes the host configuration value for the environment key.

The following example creates host configuration:

[!code-csharp]

App configuration

App configuration is created by calling xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureAppConfiguration* on IHostBuilder. ConfigureAppConfiguration can be called multiple times with additive results. The app uses whichever option sets a value last on a given key.

The configuration created by ConfigureAppConfiguration is available at HostBuilderContext.Configuration for subsequent operations and as a service from DI. The host configuration is also added to the app configuration.

For more information, see Configuration in ASP.NET Core.

Settings for all app types

This section lists host settings that apply to both HTTP and non-HTTP workloads. By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix. For more information, see the Default builder settings section.

ApplicationName

The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

Key: applicationName
Type: string
Default: The name of the assembly that contains the app's entry point.
Environment variable: <PREFIX_>APPLICATIONNAME

To set this value, use the environment variable.

ContentRoot

The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. If the path doesn't exist, the host fails to start.

Key: contentRoot
Type: string
Default: The folder where the app assembly resides.
Environment variable: <PREFIX_>CONTENTROOT

To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

For more information, see:

EnvironmentName

The IHostEnvironment.EnvironmentName property can be set to any value. Framework-defined values include Development, Staging, and Production. Values aren't case-sensitive.

Key: environment
Type: string
Default: Production
Environment variable: <PREFIX_>ENVIRONMENT

To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeout sets the timeout for xref:Microsoft.Extensions.Hosting.IHost.StopAsync*. The default value is five seconds. During the timeout period, the host:

Triggers IHostApplicationLifetime.ApplicationStopping.
Attempts to stop hosted services, logging 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.

Key: shutdownTimeoutSeconds
Type: int
Default: 5 seconds
Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

To set this value, use the environment variable or configure HostOptions. The following example sets the timeout to 20 seconds:

[!code-csharp]

Disable app configuration reload on change

By default, appsettings.json and appsettings.{Environment}.json are reloaded when the file changes. To disable this reload behavior in ASP.NET Core 5.0 or later, set the hostBuilder:reloadConfigOnChange key to false.

Key: hostBuilder:reloadConfigOnChange
Type: bool (true or 1)
Default: true
Command-line argument: hostBuilder:reloadConfigOnChange
Environment variable: <PREFIX_>hostBuilder:reloadConfigOnChange

[!WARNING] The colon (:) separator doesn't work with environment variable hierarchical keys on all platforms. For more information, see Environment variables.

Settings for web apps

Some host settings apply only to HTTP workloads. By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

Extension methods on IWebHostBuilder are available for these settings. Code samples that show how to call the extension methods assume webBuilder is an instance of IWebHostBuilder, as in the following example:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

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.

Key: captureStartupErrors
Type: bool (true or 1)
Default: Defaults to false unless the app runs with Kestrel behind IIS, where the default is true.
Environment variable: <PREFIX_>CAPTURESTARTUPERRORS

To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

When enabled, or when the environment is Development, the app captures detailed errors.

Key: detailedErrors
Type: bool (true or 1)
Default: false
Environment variable: <PREFIX_>_DETAILEDERRORS

To set this value, use configuration or call UseSetting:

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

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.

Key: hostingStartupAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

The HTTPS redirect port. Used in enforcing HTTPS.

Key: https_port
Type: string
Default: A default value isn't set.
Environment variable: <PREFIX_>HTTPS_PORT

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those URLs configured with the IServer implementation.

Key: preferHostingUrls
Type: bool (true or 1)
Default: true
Environment variable: <PREFIX_>_PREFERHOSTINGURLS

To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Prevents the automatic loading of hosting startup assemblies, including hosting startup assemblies configured by the app's assembly. For more information, see xref:fundamentals/configuration/platform-specific-configuration.

Key: preventHostingStartup
Type: bool (true or 1)
Default: false
Environment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

To set this value, use the environment variable or call UseSetting :

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

StartupAssembly

The assembly to search for the Startup class.

Key: startupAssembly
Type: string
Default: The app's assembly
Environment variable: <PREFIX_>STARTUPASSEMBLY

To set this value, use the environment variable or call UseStartup. UseStartup can take an assembly name (string) or a type (TStartup). If multiple UseStartup methods are called, the last one takes precedence.

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

URLs

A semicolon-delimited list of IP addresses or host addresses with ports and protocols that the server should listen on for requests. 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.

Key: urls
Type: string
Default: http://localhost:5000 and https://localhost:5001
Environment variable: <PREFIX_>URLS

To set this value, use the environment variable or call UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel has its own endpoint configuration API. For more information, see xref:fundamentals/servers/kestrel/endpoints.

WebRoot

The IWebHostEnvironment.WebRootPath property determines the relative path to the app's static assets. If the path doesn't exist, a no-op file provider is used.

Key: webroot
Type: string
Default: The default is wwwroot. The path to {content root}/wwwroot must exist.
Environment variable: <PREFIX_>WEBROOT

To set this value, use the environment variable or call UseWebRoot on IWebHostBuilder:

webBuilder.UseWebRoot("public");

For more information, see:

Manage the host lifetime

Call methods on the built xref:Microsoft.Extensions.Hosting.IHost implementation to start and stop the app. These methods affect all xref:Microsoft.Extensions.Hosting.IHostedService implementations that are registered in the service container.

Run

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Run* runs the app and blocks the calling thread until the host is shut down.

RunAsync

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.RunAsync* runs the app and returns a xref:System.Threading.Tasks.Task that completes when the cancellation token or shutdown is triggered.

RunConsoleAsync

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.RunConsoleAsync* enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

Start

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Start* starts the host synchronously.

StartAsync

xref:Microsoft.Extensions.Hosting.IHost.StartAsync* starts the host and returns a xref:System.Threading.Tasks.Task that completes when the cancellation token or shutdown is triggered.

xref:Microsoft.Extensions.Hosting.IHostLifetime.WaitForStartAsync* is called at the start of StartAsync, which waits until it's complete before continuing. This can be used to delay startup until signaled by an external event.

StopAsync

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.StopAsync* attempts to stop the host within the provided timeout.

WaitForShutdown

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.WaitForShutdown* blocks the calling thread until shutdown is triggered by the IHostLifetime, such as via Ctrl+C/SIGINT or SIGTERM.

WaitForShutdownAsync

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.WaitForShutdownAsync* returns a xref:System.Threading.Tasks.Task that completes when shutdown is triggered via the given token and calls xref:Microsoft.Extensions.Hosting.IHost.StopAsync*.

External control

Direct control of the host lifetime can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

::: moniker-end

::: moniker range=">= aspnetcore-3.0 < aspnetcore-5.0"

The ASP.NET Core templates create a .NET Core Generic Host (xref:Microsoft.Extensions.Hosting.HostBuilder).

This topic provides information on using .NET Generic Host in ASP.NET Core. For information on using .NET Generic Host in console apps, see .NET Generic Host.

Host definition

A host is an object that encapsulates an app's resources, such as:

Dependency injection (DI)
Logging
Configuration
IHostedService implementations

The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

Set up a host

The host is typically configured, built, and run by code in the Program class. The Main method:

Calls a CreateHostBuilder method to create and configure a builder object.
Calls Build and Run methods on the builder object.

The ASP.NET Core web templates generate the following code to create a Generic Host:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

The following code creates a Generic Host using non-HTTP workload. The IHostedService implementation is added to the DI container:

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

For an HTTP workload, the Main method is the same but CreateHostBuilder calls ConfigureWebHostDefaults:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

The preceding code is generated by the ASP.NET Core templates.

Default builder settings

The xref:Microsoft.Extensions.Hosting.Host.CreateDefaultBuilder%2A method:

Sets the content root to the path returned by xref:System.IO.Directory.GetCurrentDirectory%2A.
Loads host configuration from:
- Environment variables prefixed with DOTNET_.
- Command-line arguments.
Loads app configuration from:
- appsettings.json.
- appsettings.{Environment}.json.
- User secrets when the app runs in the Development environment.
- Environment variables.
- Command-line arguments.
Adds the following logging providers:
- Console
- Debug
- EventSource
- EventLog (only when running on Windows)
Enables scope validation and dependency validation when the environment is Development.

The ConfigureWebHostDefaults method:

Loads host configuration from environment variables prefixed with ASPNETCORE_.
Sets Kestrel server as the web server and configures it using the app's hosting configuration providers. For the Kestrel server's default options, see xref:fundamentals/servers/kestrel#kestrel-options.
Adds Host Filtering middleware.
Adds Forwarded Headers middleware if ASPNETCORE_FORWARDEDHEADERS_ENABLED equals true.
Enables IIS integration. For the IIS default options, see xref:host-and-deploy/iis/index#iis-options.

The Settings for all app types and Settings for web apps sections later in this article show how to override default builder settings.

Framework-provided services

The following services are registered automatically:

IHostApplicationLifetime
IHostLifetime
IHostEnvironment / IWebHostEnvironment

For more information on framework-provided services, see xref:fundamentals/dependency-injection#framework-provided-services.

IHostApplicationLifetime

The following example is an IHostedService implementation that registers IHostApplicationLifetime events:

[!code-csharp]

IHostLifetime

The xref:Microsoft.Extensions.Hosting.IHostLifetime implementation controls when the host starts and when it stops. The last implementation registered is used.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is the default IHostLifetime implementation. ConsoleLifetime:

Listens for Ctrl+C/SIGINT or SIGTERM and calls xref:Microsoft.Extensions.Hosting.IHostApplicationLifetime.StopApplication%2A to start the shutdown process.
Unblocks extensions such as RunAsync and WaitForShutdownAsync.

IHostEnvironment

Inject the xref:Microsoft.Extensions.Hosting.IHostEnvironment service into a class to get information about the following settings:

ApplicationName
EnvironmentName
ContentRootPath

Web apps implement the IWebHostEnvironment interface, which inherits IHostEnvironment and adds the WebRootPath.

Host configuration

Host configuration is used for the properties of the xref:Microsoft.Extensions.Hosting.IHostEnvironment implementation.

Host configuration is available from HostBuilderContext.Configuration inside xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureAppConfiguration%2A. After ConfigureAppConfiguration, HostBuilderContext.Configuration is replaced with the app config.

To add host configuration, call xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration%2A on IHostBuilder. ConfigureHostConfiguration can be called multiple times with additive results. The host uses whichever option sets a value last on a given key.

The following example creates host configuration:

[!code-csharp]

App configuration

For more information, see Configuration in ASP.NET Core.

Settings for all app types

This section lists host settings that apply to both HTTP and non-HTTP workloads. By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

ApplicationName

The IHostEnvironment.ApplicationName property is set from host configuration during host construction.

Key: applicationName
Type: string
Default: The name of the assembly that contains the app's entry point.
Environment variable: <PREFIX_>APPLICATIONNAME

To set this value, use the environment variable.

ContentRoot

The IHostEnvironment.ContentRootPath property determines where the host begins searching for content files. If the path doesn't exist, the host fails to start.

Key: contentRoot
Type: string
Default: The folder where the app assembly resides.
Environment variable: <PREFIX_>CONTENTROOT

To set this value, use the environment variable or call UseContentRoot on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

For more information, see:

EnvironmentName

The IHostEnvironment.EnvironmentName property can be set to any value. Framework-defined values include Development, Staging, and Production. Values aren't case-sensitive.

Key: environment
Type: string
Default: Production
Environment variable: <PREFIX_>ENVIRONMENT

To set this value, use the environment variable or call UseEnvironment on IHostBuilder:

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeout sets the timeout for xref:Microsoft.Extensions.Hosting.IHost.StopAsync*. The default value is five seconds. During the timeout period, the host:

Triggers IHostApplicationLifetime.ApplicationStopping.
Attempts to stop hosted services, logging errors for services that fail to stop.

Key: shutdownTimeoutSeconds
Type: int
Default: 5 seconds
Environment variable: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

To set this value, use the environment variable or configure HostOptions. The following example sets the timeout to 20 seconds:

[!code-csharp]

Settings for web apps

Some host settings apply only to HTTP workloads. By default, environment variables used to configure these settings can have a DOTNET_ or ASPNETCORE_ prefix.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.CaptureStartupErrors(true);
            webBuilder.UseStartup<Startup>();
        });

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.

To set this value, use configuration or call CaptureStartupErrors:

webBuilder.CaptureStartupErrors(true);

DetailedErrors

When enabled, or when the environment is Development, the app captures detailed errors.

Key: detailedErrors
Type: bool (true or 1)
Default: false
Environment variable: <PREFIX_>_DETAILEDERRORS

To set this value, use configuration or call UseSetting:

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

HostingStartupAssemblies

Key: hostingStartupAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

A semicolon-delimited string of hosting startup assemblies to exclude on startup.

Key: hostingStartupExcludeAssemblies
Type: string
Default: Empty string
Environment variable: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

The HTTPS redirect port. Used in enforcing HTTPS.

Key: https_port
Type: string
Default: A default value isn't set.
Environment variable: <PREFIX_>HTTPS_PORT

To set this value, use configuration or call UseSetting:

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

Indicates whether the host should listen on the URLs configured with the IWebHostBuilder instead of those URLs configured with the IServer implementation.

Key: preferHostingUrls
Type: bool (true or 1)
Default: true
Environment variable: <PREFIX_>_PREFERHOSTINGURLS

To set this value, use the environment variable or call PreferHostingUrls:

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

Key: preventHostingStartup
Type: bool (true or 1)
Default: false
Environment variable: <PREFIX_>_PREVENTHOSTINGSTARTUP

To set this value, use the environment variable or call UseSetting :

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

StartupAssembly

The assembly to search for the Startup class.

Key: startupAssembly
Type: string
Default: The app's assembly
Environment variable: <PREFIX_>STARTUPASSEMBLY

webBuilder.UseStartup("StartupAssemblyName");

webBuilder.UseStartup<Startup>();

URLs

Key: urls
Type: string
Default: http://localhost:5000 and https://localhost:5001
Environment variable: <PREFIX_>URLS

To set this value, use the environment variable or call UseUrls:

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel has its own endpoint configuration API. For more information, see xref:fundamentals/servers/kestrel#endpoint-configuration.

WebRoot

The IWebHostEnvironment.WebRootPath property determines the relative path to the app's static assets. If the path doesn't exist, a no-op file provider is used.

Key: webroot
Type: string
Default: The default is wwwroot. The path to {content root}/wwwroot must exist.
Environment variable: <PREFIX_>WEBROOT

To set this value, use the environment variable or call UseWebRoot on IWebHostBuilder:

webBuilder.UseWebRoot("public");

For more information, see:

Manage the host lifetime

Run

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Run* runs the app and blocks the calling thread until the host is shut down.

RunAsync

RunConsoleAsync

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.RunConsoleAsync* enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

Start

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Start* starts the host synchronously.

StartAsync

xref:Microsoft.Extensions.Hosting.IHost.StartAsync* starts the host and returns a xref:System.Threading.Tasks.Task that completes when the cancellation token or shutdown is triggered.

StopAsync

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.StopAsync* attempts to stop the host within the provided timeout.

WaitForShutdown

WaitForShutdownAsync

External control

Direct control of the host lifetime can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

::: moniker-end

::: moniker range="< aspnetcore-3.0"

ASP.NET Core apps configure and launch a host. The host is responsible for app startup and lifetime management.

This article covers the ASP.NET Core Generic Host (xref:Microsoft.Extensions.Hosting.HostBuilder), which is used for apps that don't process HTTP requests.

The purpose of Generic Host is to decouple the HTTP pipeline from the Web Host API to enable a wider array of host scenarios. Messaging, background tasks, and other non-HTTP workloads based on Generic Host benefit from cross-cutting capabilities, such as configuration, dependency injection (DI), and logging.

Generic Host is new in ASP.NET Core 2.1 and isn't suitable for web hosting scenarios. For web hosting scenarios, use the Web Host. Generic Host will replace Web Host in a future release and act as the primary host API in both HTTP and non-HTTP scenarios.

View or download sample code (how to download)

When running the sample app in Visual Studio Code, use an external or integrated terminal. Don't run the sample in an internalConsole.

To set the console in Visual Studio Code:

Open the .vscode/launch.json file.
In the .NET Core Launch (console) configuration, locate the console entry. Set the value to either externalTerminal or integratedTerminal.

Introduction

The Generic Host library is available in the xref:Microsoft.Extensions.Hosting namespace and provided by the Microsoft.Extensions.Hosting package. The Microsoft.Extensions.Hosting package is included in the Microsoft.AspNetCore.App metapackage (ASP.NET Core 2.1 or later).

xref:Microsoft.Extensions.Hosting.IHostedService is the entry point to code execution. Each xref:Microsoft.Extensions.Hosting.IHostedService implementation is executed in the order of service registration in ConfigureServices. xref:Microsoft.Extensions.Hosting.IHostedService.StartAsync* is called on each xref:Microsoft.Extensions.Hosting.IHostedService when the host starts, and xref:Microsoft.Extensions.Hosting.IHostedService.StopAsync* is called in reverse registration order when the host shuts down gracefully.

Set up a host

xref:Microsoft.Extensions.Hosting.IHostBuilder is the main component that libraries and apps use to initialize, build, and run the host:

[!code-csharp]

Options

xref:Microsoft.Extensions.Hosting.HostOptions configure options for the xref:Microsoft.Extensions.Hosting.IHost.

Shutdown timeout

xref:Microsoft.Extensions.Hosting.HostOptions.ShutdownTimeout* sets the timeout for xref:Microsoft.Extensions.Hosting.IHost.StopAsync*. The default value is five seconds.

The following option configuration in Program.Main increases the default five-second shutdown timeout to 20 seconds:

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

Default services

The following services are registered during host initialization:

Environment (xref:Microsoft.Extensions.Hosting.IHostingEnvironment)
xref:Microsoft.Extensions.Hosting.HostBuilderContext
Configuration (xref:Microsoft.Extensions.Configuration.IConfiguration)
xref:Microsoft.Extensions.Hosting.IApplicationLifetime (Microsoft.Extensions.Hosting.Internal.ApplicationLifetime)
xref:Microsoft.Extensions.Hosting.IHostLifetime (Microsoft.Extensions.Hosting.Internal.ConsoleLifetime)
xref:Microsoft.Extensions.Hosting.IHost
Options (xref:Microsoft.Extensions.DependencyInjection.OptionsServiceCollectionExtensions.AddOptions*)
Logging (xref:Microsoft.Extensions.DependencyInjection.LoggingServiceCollectionExtensions.AddLogging*)

Host configuration

Host configuration is created by:

Calling extension methods on xref:Microsoft.Extensions.Hosting.IHostBuilder to set the content root and environment.
Reading configuration from configuration providers in xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration*.

Extension methods

Application key (name)

The IHostingEnvironment.ApplicationName property is set from host configuration during host construction. To set the value explicitly, use the HostDefaults.ApplicationKey:

Key: applicationName
Type: string
Default: The name of the assembly containing the app's entry point.
Set using: HostBuilderContext.HostingEnvironment.ApplicationName
Environment variable: <PREFIX_>APPLICATIONNAME (<PREFIX_> is optional and user-defined)

Content root

This setting determines where the host begins searching for content files.

Key: contentRoot
Type: string
Default: Defaults to the folder where the app assembly resides.
Set using: UseContentRoot
Environment variable: <PREFIX_>CONTENTROOT (<PREFIX_> is optional and user-defined)

If the path doesn't exist, the host fails to start.

[!code-csharp]

For more information, see Fundamentals: Content root.

Environment

Sets the app's environment.

Key: environment
Type: string
Default: Production
Set using: UseEnvironment
Environment variable: <PREFIX_>ENVIRONMENT (<PREFIX_> is optional and user-defined)

The environment can be set to any value. Framework-defined values include Development, Staging, and Production. Values aren't case-sensitive.

[!code-csharp]

ConfigureHostConfiguration

xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration* uses an xref:Microsoft.Extensions.Configuration.IConfigurationBuilder to create an xref:Microsoft.Extensions.Configuration.IConfiguration for the host. The host configuration is used to initialize the xref:Microsoft.Extensions.Hosting.IHostingEnvironment for use in the app's build process.

xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration* can be called multiple times with additive results. The host uses whichever option sets a value last on a given key.

No providers are included by default. You must explicitly specify whatever configuration providers the app requires in xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration*, including:

File configuration (for example, from a hostsettings.json file).
Environment variable configuration.
Command-line argument configuration.
Any other required configuration providers.

File configuration of the host is enabled by specifying the app's base path with SetBasePath followed by a call to one of the file configuration providers. The sample app uses a JSON file, hostsettings.json, and calls xref:Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile* to consume the file's host configuration settings.

To add environment variable configuration of the host, call xref:Microsoft.Extensions.Configuration.EnvironmentVariablesExtensions.AddEnvironmentVariables* on the host builder. AddEnvironmentVariables accepts an optional user-defined prefix. The sample app uses a prefix of PREFIX_. The prefix is removed when the environment variables are read. When the sample app's host is configured, the environment variable value for PREFIX_ENVIRONMENT becomes the host configuration value for the environment key.

During development when using Visual Studio or running an app with dotnet run, environment variables may be set in the Properties/launchSettings.json file. In Visual Studio Code, environment variables may be set in the .vscode/launch.json file during development. For more information, see xref:fundamentals/environments.

Command-line configuration is added by calling xref:Microsoft.Extensions.Configuration.CommandLineConfigurationExtensions.AddCommandLine*. Command-line configuration is added last to permit command-line arguments to override configuration provided by the earlier configuration providers.

hostsettings.json:

[!code-json]

Additional configuration can be provided with the applicationName and contentRoot keys.

Example HostBuilder configuration using xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureHostConfiguration*:

[!code-csharp]

ConfigureAppConfiguration

App configuration automatically receives host configuration provided by ConfigureHostConfiguration.

Example app configuration using xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureAppConfiguration*:

[!code-csharp]

appsettings.json:

[!code-json]

appsettings.Development.json:

[!code-json]

appsettings.Production.json:

[!code-json]

To move settings files to the output directory, specify the settings files as MSBuild project items in the project file. The sample app moves its JSON app settings files and hostsettings.json with the following <Content> item:

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

[!NOTE] Configuration extension methods, such as xref:Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile* and xref:Microsoft.Extensions.Configuration.EnvironmentVariablesExtensions.AddEnvironmentVariables* require additional NuGet packages, such as Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Configuration.EnvironmentVariables. Unless the app uses the Microsoft.AspNetCore.App metapackage, these packages must be added to the project in addition to the core Microsoft.Extensions.Configuration package. For more information, see xref:fundamentals/configuration/index.

ConfigureServices

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.ConfigureServices* adds services to the app's dependency injection container. xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.ConfigureServices* can be called multiple times with additive results.

A hosted service is a class with background task logic that implements the xref:Microsoft.Extensions.Hosting.IHostedService interface. For more information, see xref:fundamentals/host/hosted-services.

The sample app uses the AddHostedService extension method to add a service for lifetime events, LifetimeEventsHostedService, and a timed background task, TimedHostedService, to the app:

[!code-csharp]

ConfigureLogging

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.ConfigureLogging* adds a delegate for configuring the provided xref:Microsoft.Extensions.Logging.ILoggingBuilder. xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.ConfigureLogging* may be called multiple times with additive results.

[!code-csharp]

UseConsoleLifetime

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.UseConsoleLifetime* listens for Ctrl+C/SIGINT or SIGTERM and calls xref:Microsoft.Extensions.Hosting.IApplicationLifetime.StopApplication* to start the shutdown process. xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.UseConsoleLifetime* unblocks extensions such as RunAsync and WaitForShutdownAsync. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime is pre-registered as the default lifetime implementation. The last lifetime registered is used.

[!code-csharp]

Container configuration

To support plugging in other containers, the host can accept an xref:Microsoft.Extensions.DependencyInjection.IServiceProviderFactory%601. Providing a factory isn't part of the DI container registration but is instead a host intrinsic used to create the concrete DI container. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>) overrides the default factory used to create the app's service provider.

Custom container configuration is managed by the xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureContainer* method. xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureContainer* provides a strongly-typed experience for configuring the container on top of the underlying host API. xref:Microsoft.Extensions.Hosting.HostBuilder.ConfigureContainer* can be called multiple times with additive results.

Create a service container for the app:

[!code-csharp]

Provide a service container factory:

[!code-csharp]

Use the factory and configure the custom service container for the app:

[!code-csharp]

Extensibility

Host extensibility is performed with extension methods on xref:Microsoft.Extensions.Hosting.IHostBuilder. The following example shows how an extension method extends an xref:Microsoft.Extensions.Hosting.IHostBuilder implementation with the TimedHostedService example demonstrated in xref:fundamentals/host/hosted-services.

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

An app establishes the UseHostedService extension method to register the hosted service passed in T:

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

Manage the host

The xref:Microsoft.Extensions.Hosting.IHost implementation is responsible for starting and stopping the xref:Microsoft.Extensions.Hosting.IHostedService implementations that are registered in the service container.

Run

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Run* runs the app and blocks the calling thread until the host is shut down:

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

RunAsync

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsync

xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.RunConsoleAsync* enables console support, builds and starts the host, and waits for Ctrl+C/SIGINT or SIGTERM to shut down.

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Start and StopAsync

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.Start* starts the host synchronously.

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.StopAsync* attempts to stop the host within the provided timeout.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync and StopAsync

xref:Microsoft.Extensions.Hosting.IHost.StartAsync* starts the app.

xref:Microsoft.Extensions.Hosting.IHost.StopAsync* stops the app.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdown

xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.WaitForShutdown* is triggered via the xref:Microsoft.Extensions.Hosting.IHostLifetime, such as Microsoft.Extensions.Hosting.Internal.ConsoleLifetime (listens for Ctrl+C/SIGINT or SIGTERM). xref:Microsoft.Extensions.Hosting.HostingAbstractionsHostExtensions.WaitForShutdown* calls xref:Microsoft.Extensions.Hosting.IHost.StopAsync*.

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

External control

External control of the host can be achieved using methods that can be called externally:

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

xref:Microsoft.Extensions.Hosting.IHostLifetime.WaitForStartAsync* is called at the start of xref:Microsoft.Extensions.Hosting.IHost.StartAsync*, which waits until it's complete before continuing. This can be used to delay startup until signaled by an external event.

IHostingEnvironment interface

xref:Microsoft.Extensions.Hosting.IHostingEnvironment provides information about the app's hosting environment. Use constructor injection to obtain the xref:Microsoft.Extensions.Hosting.IHostingEnvironment in order to use its properties and extension methods:

public class MyClass
{
    private readonly IHostingEnvironment _env;

    public MyClass(IHostingEnvironment env)
    {
        _env = env;
    }

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

For more information, see xref:fundamentals/environments.

IApplicationLifetime interface

xref:Microsoft.Extensions.Hosting.IApplicationLifetime allows for post-startup and shutdown activities, including graceful shutdown requests. Three properties on the interface are cancellation tokens used to register xref:System.Action methods that define startup and shutdown events.

Cancellation Token	Triggered when…
xref:Microsoft.Extensions.Hosting.IApplicationLifetime.ApplicationStarted*	The host has fully started.
xref:Microsoft.Extensions.Hosting.IApplicationLifetime.ApplicationStopped*	The host is completing a graceful shutdown. All requests should be processed. Shutdown blocks until this event completes.
xref:Microsoft.Extensions.Hosting.IApplicationLifetime.ApplicationStopping*	The host is performing a graceful shutdown. Requests may still be processing. Shutdown blocks until this event completes.

Constructor-inject the xref:Microsoft.Extensions.Hosting.IApplicationLifetime service into any class. The sample app uses constructor injection into a LifetimeEventsHostedService class (an xref:Microsoft.Extensions.Hosting.IHostedService implementation) to register the events.

LifetimeEventsHostedService.cs:

[!code-csharp]

xref:Microsoft.Extensions.Hosting.IApplicationLifetime.StopApplication* requests termination of the app. The following class uses xref:Microsoft.Extensions.Hosting.IApplicationLifetime.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();
    }
}

::: moniker-end

Additional resources

xref:fundamentals/host/hosted-services

67 KiB Raw Blame History

.NET Generic Host in ASP.NET Core

Host definition

Set up a host

Default builder settings

Framework-provided services

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Host configuration

App configuration

Settings for all app types

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Disable app configuration reload on change

Settings for web apps

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

URLs

WebRoot

Manage the host lifetime

Run

RunAsync

RunConsoleAsync

Start

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

External control

Host definition

Set up a host

Default builder settings

Framework-provided services

IHostApplicationLifetime

IHostLifetime

IHostEnvironment

Host configuration

App configuration

Settings for all app types

ApplicationName

ContentRoot

EnvironmentName

ShutdownTimeout

Settings for web apps

CaptureStartupErrors

DetailedErrors

HostingStartupAssemblies

HostingStartupExcludeAssemblies

HTTPS_Port

PreferHostingUrls

PreventHostingStartup

StartupAssembly

URLs

WebRoot

Manage the host lifetime

Run

RunAsync

RunConsoleAsync

Start

StartAsync

StopAsync

WaitForShutdown

WaitForShutdownAsync

External control

Introduction

Set up a host

Options

Shutdown timeout

Default services

Host configuration

Extension methods

67 KiB

Raw Blame History