skip to content

When would you use WebApplication.CreateEmptyBuilder instead of CreateBuilder in ASP.NET Core 10, and what must you add back yourself?

level: middleimportance: nice to knowfreq 16%

answer

  1. takes WebApplicationOptions, no args overload
  2. only content root and Args survive
  3. UseKestrelCore for a server
  4. AddRoutingCore before Map*
  5. smallest Native AOT footprint

basics

~20 s

CreateEmptyBuilder builds a WebApplicationBuilder with no defaults: no server, no appsettings or environment-variable configuration, no logging providers and no routing services. Use it for the smallest, fully explicit hosts, adding UseKestrelCore, AddRoutingCore and anything else yourself.

solid answer

~40 s

`WebApplication.CreateEmptyBuilder(WebApplicationOptions)` (new in .NET 8) gives a builder whose app contains only what you register. It still defaults the content root and applies `options.Args` as command-line configuration, but it adds **no** `ASPNETCORE_` or `DOTNET_` environment variables, no `appsettings.json`, no user secrets, no logging providers, no Kestrel or IIS server, no routing, host-filtering or forwarded-headers services, no developer exception page and no Development scope validation. To serve requests you add `builder.WebHost.UseKestrelCore()`; to map endpoints, `builder.Services.AddRoutingCore()`; configuration and logging sources are added by hand. It suits tiny Native AOT binaries, sidecars and test or tooling hosts where every dependency must be deliberate. `CreateBuilder` remains the right default; `CreateSlimBuilder` sits between the two.

code

csharp · 11 lines
csharp
var builder = WebApplication.CreateEmptyBuilder(new WebApplicationOptions { Args = args });

builder.WebHost.UseKestrelCore();          // no server otherwise
builder.Services.AddRoutingCore();         // needed for MapGet
builder.Configuration.AddEnvironmentVariables(); // nothing is read by default

var app = builder.Build();

app.MapGet("/ping", () => "pong");

app.Run("http://0.0.0.0:8080");

go deeper

for a junior

Recall that CreateBuilder is the normal choice and CreateEmptyBuilder starts with nothing, so a server and routing must be added by hand.

for a middle

Explain exactly what the empty builder omits — server, configuration, logging, routing, host filtering — and the calls that add each back.

for a senior

Judge when the empty builder's size and isolation gains outweigh losing configuration layering, host filtering and scope validation in production.

for a principal

Decide whether a platform needs an empty-host profile for sidecars and tools, and how to keep such hosts from drifting from the main apps' safety defaults.

## Three builders, three levels of defaults ASP.NET Core 10 offers three factory methods on `WebApplication`: | Factory | Defaults | Typical use | |---|---|---| | `CreateBuilder(args)` | Full: configuration sources, logging, Kestrel + IIS, routing, host filtering, Development scope validation | Almost every app | | `CreateSlimBuilder(args)` | Trimmed for Native AOT | AOT-published APIs | | `CreateEmptyBuilder(options)` | None beyond the content root and command-line args | Smallest binaries, fully explicit hosts | `CreateEmptyBuilder` arrived in .NET 8 alongside the Native AOT work. The release notes describe it as a builder "created with no built-in behavior" whose app "contains only the services and middleware that are explicitly configured". Unlike the others it has **no** `string[] args` overload: it requires a `WebApplicationOptions`, so arguments are passed as `new WebApplicationOptions { Args = args }`. ## What the empty builder still does - It defaults the **content root** the same way every `WebApplicationBuilder` does. - It applies `WebApplicationOptions.Args` as **command-line configuration**, plus the `EnvironmentName`, `ApplicationName`, `ContentRootPath` and `WebRootPath` you set. - At `Build()` and start-up, `WebApplication` still wires routing and endpoint execution around your pipeline when endpoints exist, and adds authentication and authorization middleware when their services are registered. ## What it leaves out - **No server.** Neither Kestrel nor IIS is registered, so the app fails at start because no `IServer` is available. `builder.WebHost.UseKestrelCore()` registers Kestrel without the HTTPS-configuration and HTTP/3 (QUIC) pieces that `UseKestrel()` adds, and nothing binds the `Kestrel` configuration section. - **No configuration sources** beyond the args: no `appsettings*.json`, no user secrets, no environment variables — not even `ASPNETCORE_` ones, so `ASPNETCORE_ENVIRONMENT` is not read. - **No logging providers.** `ILogger<T>` resolves, but nothing is written until a provider is added. - **No routing services.** `MapGet` followed by the automatic `UseRouting` fails with *"Unable to find the required services. Please add all the required services by calling 'IServiceCollection.AddRouting' ..."* until `builder.Services.AddRoutingCore()` (or `AddRouting()`) is called. - **No host filtering or forwarded headers**, which `CreateBuilder` installs through startup filters. - **No developer exception page**, even in Development. - **No `ValidateScopes` / `ValidateOnBuild`** in Development. ## A minimal working empty host The pieces that make it serve one endpoint are few: 1. `CreateEmptyBuilder(new WebApplicationOptions { Args = args })`; 2. `builder.WebHost.UseKestrelCore()` for a server; 3. `builder.Services.AddRoutingCore()` for endpoint routing; 4. optional: `builder.Configuration.AddEnvironmentVariables()` and a logging provider if the app needs them; 5. `Build()`, `MapGet`, `Run()`. The `url` argument of `Run`, or `app.Urls`, gives Kestrel an address, since no `urls` configuration is read unless you add a source for it. ## When it is worth it - **Native AOT binaries where every kilobyte counts.** What is not referenced can be trimmed; the .NET 8 release notes cite a self-contained native executable of about 8.5 MB for a small empty-builder app on linux-x64. - **Sidecars and probes** that answer one endpoint and must not pick up a shared `appsettings.json` or environment variables meant for the main app. - **Test or tooling hosts** where hidden defaults would make results depend on the machine. ## When it is not For a normal API the missing defaults are features: configuration layering, logging, host filtering, IIS support and scope validation all protect production. Re-adding them one by one recreates `CreateBuilder` with more code and more chances to forget one. If the goal is Native AOT, `CreateSlimBuilder` is the usual starting point; `CreateEmptyBuilder` is the choice only when even that is too much. ## Interview angle The question is rarely "have you used it?" — few teams have. It tests whether a candidate knows **what `CreateBuilder` silently provides**, by asking what disappears without it. A strong answer lists the missing pieces by category (server, configuration, logging, routing, protective middleware, Development diagnostics), names the calls that restore the two that block a working app (`UseKestrelCore`, `AddRoutingCore`), and explains why most production apps should not take this route. Mentioning that `ASPNETCORE_ENVIRONMENT` and `ASPNETCORE_URLS` are ignored unless a source is added shows the candidate has traced how configuration reaches the host rather than memorised a list.

  • An app built with WebApplication.CreateEmptyBuilder maps an endpoint but fails at startup asking for AddRouting. Why?
    The empty builder registers no routing services. `WebApplication` still inserts `UseRouting` when endpoints exist, and `UseRouting` verifies the routing services and throws. Call `builder.Services.AddRoutingCore()` (or `AddRouting()`) before `Build()`.
  • Does ASPNETCORE_ENVIRONMENT=Development affect an app built with CreateEmptyBuilder?
    No. The empty builder adds no environment-variable configuration, so the environment stays Production unless `WebApplicationOptions.EnvironmentName` or a command-line argument sets it, or you add an environment-variable source yourself.

  • CreateEmptyBuilder still registers Kestrel, it just skips appsettings.json
  • An empty-builder app reads its listening address from ASPNETCORE_URLS
  • Logging works out of the box because ILogger<T> resolves
  • The empty builder still reads ASPNETCORE_ENVIRONMENT
  • CreateEmptyBuilder is the recommended starting point for any small API