Edit

Share via

WebHostBuilder, IWebHost, and WebHost are obsolete

WebHostBuilder, IWebHost, and WebHost have been marked as obsolete in .NET 10. WebHostBuilder was replaced by HostBuilder (generic host) in ASP.NET Core 3.0, and WebApplicationBuilder was introduced in ASP.NET Core 6.0. These newer alternatives are where future investments will occur.

Version introduced

.NET 10 RC 1

Previous behavior

Previously, you could use WebHostBuilder to configure and build a web host without any compile-time warnings.

New behavior

Starting in .NET 10, using WebHostBuilder produces 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 produces 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

This change can affect source compatibility.

Reason for change

HostBuilder and WebApplication have all the features of WebHostBuilder and are the focus of future investment. WebHostBuilder was replaced by the generic host in ASP.NET Core 3.0, and minimal APIs with WebApplicationBuilder were introduced in ASP.NET Core 6.0. These newer hosting models provide better integration with the .NET ecosystem and are the recommended approach for new applications.

Migrate from WebHostBuilder to either HostBuilder or WebApplication:

  • For applications that need the full hosting capabilities, migrate 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();

  • For new applications, especially those using minimal APIs, migrate to WebApplicationBuilder.

Affected APIs

See also