---
title: Create the default host builder
summary: Assembles the IHostBuilder with the configuration-source stack and Windows Service hosting.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.WindowsService
reference_type: package
operation_id: OP-03
trigger: OP-02 step 1, normally through the consumer override's base.CreateHostBuilder(args) call
---

# Create the default host builder

| Field | Value |
| --- | --- |
| **Operation ID** | OP-03 |
| **Trigger** | [Create and configure the host](op-02-create-host.md) step 1 (normally through the consumer override's `base.CreateHostBuilder(args)` call) |
| **Inputs** | `args` |
| **Outputs** | `IHostBuilder` |
| **Primary components** | `ServiceProgramRunnerBase.CreateHostBuilder` |
| **Entry point** | `src/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/ServiceProgramRunnerBase.cs` |

## Steps

1. Call `Host.CreateDefaultBuilder(args)`.
   - Framework-standard: content root, default configuration sources (host configuration, `appsettings.json`, `appsettings.{Environment}.json`, user secrets in Development, environment variables, command-line args), console/debug/EventSource/EventLog logging providers, and DI scope validation in Development.
2. Append configuration sources through `ConfigureAppConfiguration`: `AddJsonFile("appsettings.json", optional: true)` and `AddEnvironmentVariables()` ([WS-BR-03](../business-rules.md#ws-br-03-configuration-source-stack-is-altered-by-re-added-providers)).
   - Effect: because later providers win, these re-added sources take precedence over the command-line source and over `appsettings.{Environment}.json`, inverting the standard .NET precedence order. See [Configuration](../configuration.md) for the full consequence list.
3. Enable Windows Service hosting with `.UseWindowsService()`.
   - Sets `WindowsServiceLifetime` and the content root to `AppContext.BaseDirectory` when the process runs under the SCM; it is a no-op otherwise, so the same executable runs as a console app for debugging.
4. Return the builder. The library registers no services itself.

## Process flow

```mermaid
flowchart TD
	Start([CreateHostBuilder args]) --> Default[Host.CreateDefaultBuilder args]
	Default --> Append[Re-append appsettings.json and env vars]
	Append --> Windows[UseWindowsService]
	Windows --> Return([Return IHostBuilder])
```

## Failure and edge-case behavior
- None specific to this operation; failures from the appended providers surface later when a key is read (for example, `DelayStart` in [Create and configure the host](op-02-create-host.md)).
- Running outside the SCM makes `.UseWindowsService()` a no-op, so the process behaves as a plain console app.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `src/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/SAIF.NetCore.WindowsService/ServiceProgramRunnerBase.cs`