Skip to content

Add guidance for selecting IHostApplicationBuilder vs IHostBuilder #51460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gewarren merged 4 commits into from
Feb 4, 2026
+12 −1
Merged

Add guidance for selecting IHostApplicationBuilder vs IHostBuilder #51460

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d742e0c
Initial plan
Copilot Feb 4, 2026
573da83
Add section explaining IHostApplicationBuilder vs IHostBuilder select…
Copilot Feb 4, 2026
3b18d73
Apply suggestions from code review
gewarren Feb 4, 2026
42b9eb8
Apply suggestions from code review
gewarren Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/core/extensions/generic-host.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
---
title: .NET Generic Host
description: Learn about the .NET Generic Host, which is responsible for app startup and lifetime management.
ms.date: 09/11/2024
ms.date: 02/04/2026
ai-usage: ai-assisted
---

# .NET Generic Host
Expand All @@ -20,6 +21,16 @@ When a host starts, it calls <xref:Microsoft.Extensions.Hosting.IHostedService.S

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.

## Host builder options

.NET provides two approaches for configuring and building a Generic Host:

- <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> (`Host.CreateApplicationBuilder`): Introduced in .NET 6, this approach uses a linear, property-based configuration style. Services, configuration, and logging are configured by directly accessing properties on the builder object (for example, `builder.Services`, `builder.Configuration`). This approach is recommended for new projects and is the default in current .NET templates.

- <xref:Microsoft.Extensions.Hosting.IHostBuilder> (`Host.CreateDefaultBuilder`): This is the traditional callback-based approach where configuration is done through chained extension methods (for example, `ConfigureServices`, `ConfigureAppConfiguration`). While fully supported, this legacy approach works best for maintaining compatibility with existing codebases.

Both approaches provide the same core functionality and default behaviors. Choose `IHostApplicationBuilder` for new projects to align with modern .NET patterns and simpler configuration code. Use `IHostBuilder` when maintaining existing applications or when third-party libraries require the callback-based pattern.

## Set up a host

The host is typically configured, built, and run by code in the `Program` class. The `Main` method:
Expand Down