[Breaking change]: Deprecating WebHostBuilder, IWebHost, and WebHost

[BrennanConroy]

Description

WebHostBuilder was replaced by HostBuilder (generic host) in 3.0 and we also added WebApplicationBuilder in 6.0.

We are now marking WebHostBuilder as obsolete to encourage users to move on to the alternatives which is where future investments will occur, and we're also marking IWebHost and WebHost as deprecated to clean up other parts of the now obsolete web host story.

Version

.NET 10 RC 1

Previous behavior

var hostBuilder = new WebHostBuilder()
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseStartup()
    .UseKestrel();
// Test code might use TestServer:
var testServer = new TestServer(hostBuilder);

New behavior

Using WebHostBuilder will produce a compiler warning with diagnostic ID ASPDEPR004:

warning ASPDEPR004: WebHostBuilder is deprecated in favor of HostBuilder and WebApplicationBuilder. For more information, visit https://aka.ms/aspnet/deprecate/004.

Using IWebHost or WebHost will produce a compiler warning with diagnostic ID ASPDEPR008:

warning ASPDEPR008: WebHost is obsolete. Use HostBuilder or WebApplicationBuilder instead. For more information, visit https://aka.ms/aspnet/deprecate/008.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

We recommend the use of HostBuilder and WebApplication going forward over WebHostBuilder because they have all the features of WebHostBuilder and will be the focus of future investment.

Recommended action

See https://learn.microsoft.com/aspnet/core/fundamentals/host/generic-host or https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis/webapplication for more details on the different hosting models. As well as HostBuilder replaces WebHostBuilder and Introducing WebApplication for migration guides.

Below is an example of converting WebHostBuilder to HostBuilder:

Before

var hostBuilder = new WebHostBuilder()
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseStartup()
    .UseKestrel();
// Test code might use TestServer:
var testServer = new TestServer(hostBuilder);

After

using var host = new HostBuilder()
    .ConfigureWebHost(webHostBuilder =>
    {
        webHostBuilder
            .UseTestServer() // If using TestServer
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseStartup()
            .UseKestrel();
    })
    .Build();
await host.StartAsync();

var testServer = host.GetTestServer();

Both Copilot and ChatGpt have given good results so far when asked to convert a WebHostBuilder example to use HostBuilder. Below is an example prompt:

Example AI Prompt

Can you convert

var hostBuilder = new WebHostBuilder()
.UseContentRoot(Directory.GetCurrentDirectory())
.UseStartup()
.UseKestrel();
// Test code might use TestServer:
var testServer = new TestServer(hostBuilder);

to use HostBuilder.

Affected APIs

public class Microsoft.AspNetCore.Hosting.WebHostBuilder
public interface Microsoft.AspNetCore.Hosting.IWebHost
public static class Microsoft.AspNetCore.WebHost

Discussion

dotnet/aspnetcore#63480