The Generic Host

The host is the object that owns everything outside your business logic: the configuration, the service container, the logging factory, and the lifetime of any long-running work. It is called the generic host because it is not specific to web applications — a console tool, a message consumer and an API all use the same one, and a web application adds its server on top of it.

Three lessons in this course described pieces that appear from somewhere: layered configuration, a container with registrations, loggers with categories and levels. The host is that somewhere. It is a small amount of code that assembles them in a fixed order and then hands you the result.

The word for this shape is a composition root: one place where the application is assembled, running once at start-up, after which nothing else constructs anything. Everything in the rest of your codebase asks for what it needs and receives it.

You will meet an older spelling in existing code: Host.CreateDefaultBuilder with ConfigureServices and ConfigureAppConfiguration callbacks. It does the same work in a different shape. Newer code uses Host.CreateApplicationBuilder, which exposes Configuration, Services, Logging and Environment as properties rather than as callbacks.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services
    .AddOptions<EmployeeOptions>()
    .Bind(builder.Configuration.GetSection(EmployeeOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

builder.Services.AddSingleton<IClock, SystemClock>();
builder.Services.AddScoped<IEmployeeStore, PostgresEmployeeStore>();
builder.Services.AddScoped<EmployeeService>();

// Long-running work, started by the host and stopped by it
builder.Services.AddHostedService<EmployeeSyncWorker>();

using IHost host = builder.Build();
await host.RunAsync();

• Fifteen lines, and the application now has layered configuration, validated options, a container, logging and a managed background worker. That is the return on using a host rather than a plain Main method.
• Everything before Build is registration. Everything after it is running. Keeping that boundary sharp is what makes start-up possible to reason about — there is exactly one place where the application is assembled.
• AddHostedService registers a class the host will start and stop. The host owns its lifetime; nothing in your code calls it.
• The using declaration on the host matters. Disposing it disposes the container, which disposes every singleton that implements IDisposable. Without it, cleanup on shutdown is left to chance.
• RunAsync starts the hosted services and then waits for a stop request. Control does not come back to the next line until the host is stopping.

// Start and finish: runs once during start-up, cleans up during shutdown
public sealed class PayrollConnectionWarmup(
    IPayrollClient client,
    ILogger<PayrollConnectionWarmup> logger) : IHostedService
{
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        // The host is waiting for this to return, so keep it short
        await client.OpenAsync(cancellationToken);
        logger.LogInformation("Payroll connection ready");
    }

    public Task StopAsync(CancellationToken cancellationToken) =>
        client.CloseAsync(cancellationToken);
}

// A loop: runs for the life of the process
public sealed class LeaveAccrualWorker(
    IServiceScopeFactory scopeFactory,
    ILogger<LeaveAccrualWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromHours(1));

        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            using IServiceScope scope = scopeFactory.CreateScope();
            var service = scope.ServiceProvider.GetRequiredService<EmployeeService>();
            int accrued = await service.AccrueLeaveAsync(stoppingToken);
            logger.LogInformation("Accrued leave for {EmployeeCount} employees", accrued);
        }
    }
}

• StartAsync is awaited by the host before it moves on. The application is not running yet while you are inside it, so a slow call here delays start-up for everything — and a call that never returns means the application never starts, with no error to explain the hang.
• PeriodicTimer with WaitForNextTickAsync is a cleaner loop than a delay inside a while, because the token is handled by the wait. When the host stops, WaitForNextTickAsync throws a cancellation exception that the host treats as an ordinary stop rather than a failure.
• The worker creates a scope per cycle instead of taking EmployeeService in its constructor. A background service is effectively a singleton, so a scoped dependency in its constructor would be captive — the dependency injection lesson covers the damage that causes.
• The token is passed all the way down into AccrueLeaveAsync. A worker that accepts a token and never forwards it cannot be stopped promptly, which becomes the lifecycle lesson's problem.
• An unhandled exception escaping ExecuteAsync stops the whole host by default. That is deliberate — a worker that has silently died while the process stays healthy is worse than a crash — so decide explicitly which failures you catch and retry inside the loop.