asp.net core - What is the difference between IWebHost WebHostBuilder BuildWebHost

Question

After reading Microsoft documents I am still confused. I need to deploy a .net core 2 web application I developed to an IIS server and I can't get a straight forward answer on anything. This is just the beginning of my questions.

What is the difference between IWebHost, WebHostBuilder, BuildWebHost?

Thanks!

Answer 1

First of all, let me start with that I very much disagree with your statement: The documentation on ASP.NET Core is actually very good. Yes, it may be still lacking in some details, and it also has some problems catching up to changes with releases, but overall the content is really good and the team working on it is really doing a remarkable job. It’s really difficult to author a documentation for such a large and fast-moving framework, and the amount of information you get through the documentation is actually very good. You will likely get to recognize that once you have overcome the initial problems in starting with a new framework.

But coming back to your question:

• IWebHost: The web host is the general thing that hosts and runs your web application. It gets created when your application starts up, and then it will construct all the necessary pieces, like the Kestrel web server, the application middleware pipeline, and all the other bits, and connects them, so that your application is ready to serve your requests.

  The web host is basically the thing that makes up your web application.

• IWebHostBuilder: The web host builder is basically a factory to create a web host. It is the thing that constructs the web host but also configures all the necessay bits the web host needs to determine how to run the web application.

  With ASP.NET Core 2, you will usually create a “default web host builder” which will already come with a lot defaults. For example, the default web host will set up the Kestrel web server, enable and configure logging, and add support for the appsettings.json configuration.

  Usually, your applications will always start with such a default web host and you then just use the web host builder to subsequently configure the web host before it is actually being built.

• BuildWebHost is part of the older convention before ASP.NET Core 2.1 where the default pattern in the Program.cs was to build the web host in a separate method. With 2.1, this was changed so that the method would no longer build the web host directly but just create the web host builder (hence the method now being called CreateWebHostBuilder). So basically, the .Build() call on the web host builder was refactored out of the method. You can see this nicely in the migration guide for 2.0 to 2.1.

  The reason this was done is to make the CreateWebHostBuilder reuseable. The builder configuration that happens in that method is basically everything that is necessary to configure the web host. So by making that reusable, without generating an actually created web host, it can be used for other purposes. In this case, this was done for integration testing using the TestHost. The test host will basically host the web host internally for your integration tests, and it will do so by looking for the CreateWebHostBuilder method.

With ASP.NET Core 2.1, the default pattern you see in the Program.cs is the following (comments added by me for further explanations):

public class Program
{
    // main entry point for your application
    public static void Main(string[] args)
    {
        // create the web host builder
        CreateWebHostBuilder(args)
            // build the web host
            .Build()
            // and run the web host, i.e. your web application
            .Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        // create a default web host builder, with the default settings and configuration
        WebHost.CreateDefaultBuilder(args)
            // configure it to use your `Startup` class
            .UseStartup<Startup>();
}

Btw. this topic is generally covered in the application startup and hosting sections of the official documentation.

ASP.NET Core 3.x

Starting with ASP.NET Core 3.0, there has been a change with the setup I described above. The reason for this is the generic host. The “generic host” is a generalization of the web host and the web host builder, to allow non-web scenarios outside of ASP.NET Core, making ASP.NET Core itself just a “hosted service” that runs on top of the generic host.

• IHost: The host is the component that hosts and runs your application and its services. This is a generalization of the previous IWebHost but fullfills basically the same task: It starts configured hosted services and makes sure that your app is running and working.

• IHostBuilder: The host builder constructs the host and configures various services. This is the generalization of the previous IWebHostBuilder but also basically does the same just for generic IHost. It configures the host before the application starts.

  There is the Host.CreateDefaultBuilder method that will set up a host with various defaults, e.g. configuration using appsettings.json and logging.

• IHostedService: A hosted service is a central component that the host hosts. The most common example would be the ASP.NET Core server, which is implemented as a hosted service on top of the generic host.

  You can also write your own hosted services, or add third-party services that allow you to nicely add things to your application.

The generic host introduced with ASP.NET Core 3.0 and .NET Core 3.0 basically replaces the previous IWebHost and IWebHostBuilder. It follows the very same architecture and idea but is simply reduced to non-web tasks so that it can work with a number of different purposes. ASP.NET Core then just builds on top of this generic host.