[API Proposal]: Host.CreateEmptyApplicationBuilder

[eerhardt]

Background and motivation

In .NET 8, we are enabling ASP.NET Minimal APIs to support NativeAOT. As part of this effort, our goal is to get the template app's publish size to 10 MB. To meet this goal, we need to cut unnecessary dependencies in the application.

Some of the unnecessary dependencies come from the Microsoft.Extensions.Hosting.HostApplicationBuilder API. Specifically, the Microsoft.Extensions.Configuration.Json usage for appsettings.json and optional Logging services (Console, Debug, EventSource, EventLog).

We should create a way to create an "empty" HostApplicationBuilder that doesn't bring any of these optional/unnecessary dependencies into the app's closure. Functionally, this would behave the same as new HostApplicationBuilder(new HostApplicationBuilderSettings() { DisableDefaults = true }).

This should cut about 1.3 MB of a NativeAOT published Windows x64 app. Prototyping this change on my machine results the Benchmark app:

Before
15.2 MB (16,007,168 bytes)

After
13.9 MB (14,593,024 bytes)

And 1.4MB on Linux x64:

Before
18.6 MB (19,601,424 bytes)

After
17.2 MB (18,132,768 bytes)

The bulk of this size savings (~1MB) is due to the Console Logger getting trimmed from the app. A follow up issue will be logged to make Console Logging smaller when used/needed.

API Proposal

namespace Microsoft.Extensions.Hosting;

public static class Host
{
        public static HostApplicationBuilder CreateApplicationBuilder();
        public static HostApplicationBuilder CreateApplicationBuilder(string[]? args);
+       public static HostApplicationBuilder CreateEmptyApplicationBuilder(HostApplicationBuilderSettings? settings);
        public static IHostBuilder CreateDefaultBuilder();
        public static IHostBuilder CreateDefaultBuilder(string[]? args);
}
public sealed partial class HostApplicationBuilder
{
    public HostApplicationBuilder() { }
    public HostApplicationBuilder(HostApplicationBuilderSettings? settings) { }
    public HostApplicationBuilder(string[]? args) { }
}

API Usage

var builder = Host.CreateEmptyApplicationBuilder(new HostApplicationBuilderSettings
{
    Args = args,
    ApplicationName = "My App",
    EnvironmentName = "Production",
    ContentRootPath = Environment.CurrentDirectory
    Configuration = new ConfigurationManager(),
});

// do the same things with `builder` as normal
builder.Logging.AddConsole();
builder.Services.AddScoped(_ => new SqliteConnection(connectionString));

IHost host = builder.Build();
host.Run();

Alternative Designs

Create a whole new, duplicate HostApplicationBuilder class that doesn't have these dependencies.

Risks

Users expecting the default behavior of new HostApplicationBuilder() being the same as Host.CreateEmptyApplicationBuilder(new HostApplicationBuilderSettings()).

Tagging subscribers to this area: @dotnet/area-extensions-hosting
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

In .NET 8, we are enabling ASP.NET Minimal APIs to support NativeAOT. As part of this effort, our goal is to get the template app's publish size to 10 MB. To meet this goal, we need to cut unnecessary dependencies in the application.

Some of the unnecessary dependencies come from the Microsoft.Extensions.Hosting.HostApplicationBuilder API. Specifically, the Microsoft.Extensions.Configuration.Json usage for appsettings.json and optional Logging services (Console, Debug, EventSource, EventLog).

We should create a way to create an "empty" HostApplicationBuilder that doesn't bring any of these optional/unnecessary dependencies into the app's closure. Functionally, this would behave the same as new HostApplicationBuilder(new HostApplicationBuilderSettings() { DisableDefaults = true }).

In prototyping this API, it saves roughly 300 KB in the published Linux x64 app.

API Proposal

namespace Microsoft.Extensions.Hosting;

public static class Host
{
        public static HostApplicationBuilder CreateApplicationBuilder();
        public static HostApplicationBuilder CreateApplicationBuilder(string[]? args);
+       public static HostApplicationBuilder CreateEmptyApplicationBuilder(HostApplicationBuilderSettings? settings);
        public static IHostBuilder CreateDefaultBuilder();
        public static IHostBuilder CreateDefaultBuilder(string[]? args);
}
public sealed partial class HostApplicationBuilder
{
    public HostApplicationBuilder() { }
    public HostApplicationBuilder(HostApplicationBuilderSettings? settings) { }
    public HostApplicationBuilder(string[]? args) { }
}

API Usage

var builder = Host.CreateEmptyApplicationBuilder(new HostApplicationBuilderSettings
{
    Args = args,
    ApplicationName = "My App",
    EnvironmentName = "Production",
    ContentRootPath = Environment.CurrentDirectory
    Configuration = new ConfigurationManager(),
});

// do the same things with `builder` as normal
builder.Logging.AddConsole();
builder.Services.AddScoped(_ => new SqliteConnection(connectionString));

IHost host = builder.Build();
host.Run();

Alternative Designs

Create a whole new, duplicate HostApplicationBuilder class that doesn't have these dependencies.

Risks

Users expecting the default behavior of new HostApplicationBuilder() being the same as Host.CreateEmptyApplicationBuilder(new HostApplicationBuilderSettings()).

Author:	eerhardt
Assignees:	-
Labels:	api-suggestion, blocking, area-Extensions-Hosting
Milestone:	-

[eerhardt]

cc @davidfowl @halter73

[terrajobst]

Is Empty the right name when it comes with, for example, DI? Would a better name be CreateMinimalAppBuilder()?

[eerhardt]

"Hosting" implies that there is DI. It is intrinsic to what the Hosting layer provides. A HostApplicationBuilder builds an IHost. IHost has 3 things:

runtime/src/libraries/Microsoft.Extensions.Hosting.Abstractions/src/IHost.cs

Lines 13 to 34 in a342915

	public interface IHost : IDisposable
	{
	/// <summary>
	/// Gets the services configured for the program (for example, using <see cref="M:HostBuilder.ConfigureServices(Action&lt;HostBuilderContext,IServiceCollection&gt;)" />).
	/// </summary>
	IServiceProvider Services { get; }
	/// <summary>
	/// Starts the <see cref="IHostedService" /> objects configured for the program.
	/// The application will run until interrupted or until <see cref="M:IHostApplicationLifetime.StopApplication()" /> is called.
	/// </summary>
	/// <param name="cancellationToken">Used to abort program start.</param>
	/// <returns>A <see cref="Task"/> that will be completed when the <see cref="IHost"/> starts.</returns>
	Task StartAsync(CancellationToken cancellationToken = default);
	/// <summary>
	/// Attempts to gracefully stop the program.
	/// </summary>
	/// <param name="cancellationToken">Used to indicate when stop should no longer be graceful.</param>
	/// <returns>A <see cref="Task"/> that will be completed when the <see cref="IHost"/> stops.</returns>
	Task StopAsync(CancellationToken cancellationToken = default);
	}

1. DI Services
2. You can Start it
3. You can Stop it

"Empty" means there are no registered services. i.e. there are no Logging or Configuration providers (or other "optional" services).

[terrajobst]

"Hosting" implies that there is DI. It is intrinsic to what the Hosting layer provides. [...]
"Empty" means there are no registered services. i.e. there are no Logging or Configuration providers (or other "optional" services).

Gotcha, that makes total sense.

[bartonjs]

Video

Through a lot of adding and removing things during the discussion, we added an overload of CreateApplicationBuilder that takes the settings object for symmetry and a clear path from the existing pattern to the new one. This new overload is a source-breaking change for the null literal, but we believe the number of callers will be small enough that it's not a concern.

namespace Microsoft.Extensions.Hosting;

public static class Host
{
        public static HostApplicationBuilder CreateApplicationBuilder();
+       public static HostApplicationBuilder CreateApplicationBuilder(HostApplicationBuilderSettings? settings);
        public static HostApplicationBuilder CreateApplicationBuilder(string[]? args);
+       public static HostApplicationBuilder CreateEmptyApplicationBuilder(HostApplicationBuilderSettings? settings);
        public static IHostBuilder CreateDefaultBuilder();
        public static IHostBuilder CreateDefaultBuilder(string[]? args);
}
public sealed partial class HostApplicationBuilder
{
    public HostApplicationBuilder() { }
    public HostApplicationBuilder(HostApplicationBuilderSettings? settings) { }
    public HostApplicationBuilder(string[]? args) { }
}