WebApplication.CreateBuilder vs Host.CreateDefaultBuilder: A Complete Guide

Introduction

When building .NET applications, developers have two primary options for creating and configuring application hosts: WebApplication.CreateBuilder() and Host.CreateDefaultBuilder(). Understanding the differences between these approaches is crucial for making informed architectural decisions.

WebApplication.CreateBuilder()

Introduced in .NET 6, WebApplication.CreateBuilder() provides a streamlined approach for creating web applications with minimal setup.

Key Features

• Simplified API: Reduces boilerplate code significantly
• Built-in web defaults: Automatically configures common web services
• Integrated hosting: Combines host and web server configuration
• Top-level programs: Works seamlessly with minimal APIs

Example Usage

var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddControllers();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure pipeline
app.UseSwagger();
app.UseSwaggerUI();
app.MapControllers();

app.Run();

Host.CreateDefaultBuilder()

The traditional approach available since .NET Core 2.0, providing full control over host configuration.

Key Features

• Generic host: Can host any type of .NET application
• Explicit configuration: Requires manual setup of web-specific services
• Maximum flexibility: Full control over all host aspects
• Legacy compatibility: Works with older .NET versions

Example Usage

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>();
            });
}

Key Differences

When to Use Each

Use WebApplication.CreateBuilder() When:

• Building new web applications on .NET 6+
• Preferring minimal APIs and simplified setup
• Working with small to medium-sized applications
• Wanting built-in web optimizations

Use Host.CreateDefaultBuilder() When:

• Building non-web applications (worker services, console apps)
• Requiring maximum configuration flexibility
• Working with legacy codebases
• You need complex startup logic separation

Performance Considerations

WebApplication.CreateBuilder() includes optimizations for web scenarios:

• Pre-configured JSON serialization
• Optimized middleware pipeline
• Reduced memory allocation during startup

Migration Path

Converting from Host.CreateDefaultBuilder() to WebApplication.CreateBuilder():

// Before
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });

// After
var builder = WebApplication.CreateBuilder(args);
// Move Startup.ConfigureServices content here
// Move Startup.Configure content after builder.Build()

Conclusion

Both approaches have their place in modern .NET development. WebApplication.CreateBuilder() offers simplicity and web-optimized defaults for most web applications, while Host.CreateDefaultBuilder() provides maximum flexibility for complex scenarios and non-web applications. Choose based on your specific requirements, target framework, and complexity needs.

Next Blog Ideas

• Dependency Injection Container Differences: How WebApplication.CreateBuilder() uses a different DI container setup and the performance implications of container choices
• Custom Host Configuration: Comparing custom configuration options between both approaches
• Multiple Environment Handling: Environment-specific configurations and best practices
• Custom Service Provider Integration: Advanced scenarios for service provider customization