.NET Generic Host in ASP.NET Core

The ASP.NET Core templates create a .NET Core Generic Host (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 IHostedService.StartAsync on each implementation of 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 CreateDefaultBuilder method:

• Sets the content root to the path returned by 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 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 Configure options for the ASP.NET Core Kestrel web server.
• Adds Host Filtering middleware.
• Adds Forwarded Headers middleware if ASPNETCORE_FORWARDEDHEADERS_ENABLED equals true.
• Enables IIS integration. For the IIS default options, see Host ASP.NET Core on Windows with IIS.

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

GenericHostBuilderExtensions.ConfigureWebHostDefaults(IHostBuilder, Action<IWebHostBuilder>) Method

Remarks

The following defaults are applied to the IHostBuilder:

• use Kestrel as the web server and configure it using the application‘s configuration providers
• configure WebRootFileProvider to include static web assets from projects referenced by the entry assembly during development
• adds the HostFiltering middleware
• adds the ForwardedHeaders middleware if ASPNETCORE_FORWARDEDHEADERS_ENABLED=true,
• enable IIS integration

What is the difference between ConfigureWebHostDefaults and ConfigureWebHost methods?

        public static IHostBuilder ConfigureWebHostDefaults(this IHostBuilder builder, Action<IWebHostBuilder> configure)
        {
            return builder.ConfigureWebHost(webHostBuilder =>
            {
                WebHost.ConfigureWebDefaults(webHostBuilder);

                configure(webHostBuilder);
            });
        }

.NET Generic Host in ASP.NET Core