[API Proposal]: Add IHostApplicationBuilder interface

[eerhardt]

Background and motivation

In .NET 6, ASP.NET added a WebApplicationBuilder "minimal hosting" API. This was a new, non-callback approach to the HostBuilder Generic Host API. In .NET 7, Extensions.Hosting added a similar "generic host" API that followed the same non-callback API design.

The problem is these two hosting APIs have the same members (mostly), but don't have a common base abstraction that libraries can add extension methods to. In the previous, callback API IHostBuilder was the interface libraries could extend and add their library-specific DI services, etc. to.

To enable this, we should add a general abstraction to these hosting builder APIs.

See the conversations at:

• Update the Worker template to use Host.CreateApplicationBuilder aspnetcore#47720 (comment)
• tweak that simplifies Worker startup code aspnetcore#43056

API Proposal

namespace Microsoft.Extensions.Hosting;

public interface IHostApplicationBuilder
{
    IDictionary<object, object> Properties { get; }

    IConfigurationManager Configuration { get; }
    IHostEnvironment Environment { get; }
    ILoggingBuilder Logging { get; }
    IServiceCollection Services { get; }

    IHost Build();  // See Note below on `Build()`
    void ConfigureContainer<TContainerBuilder>(IServiceProviderFactory<TContainerBuilder>factory, Action<TContainerBuilder>? configure = null) where TContainerBuilder: notnull;
}

-public sealed class HostApplicationBuilder {}
+public sealed class HostApplicationBuilder : IHostApplicationBuilder {}

namespace Microsoft.Extensions.Configuration;

public interface IConfigurationManager : IConfiguration, IConfigurationBuilder
{
}

-public sealed class ConfigurationManager : IConfigurationBuilder, IConfigurationRoot, IDisposable {}
+public sealed class ConfigurationManager : IConfigurationBuilder, IConfigurationRoot, IDisposable, IConfigurationManager {}

Note on Build()

If we wanted to make this API work for all ApplicationBuilders like MauiAppBuilder and WebAssemblyHostBuilder, we would need to think about IHost Build(). Those 2 app models follow this same ApplicationBuilder pattern, but the things they build don't implement IHost. Options here are:

• Don't put Build() in the interface. But the name of the interface is "Builder", so it doesn't feel right to not have a Build method.
• For the app models that don't support IHost, they would throw NotSupported for this method. This is my recommendation.

API Usage

Using an existing extension method on IHostBuilder as an example, a new extension method could be written like:

public static class HostBuilderExtensions
{
    public static IHostBuilder AddSteeltoe(this IHostApplicationBuilder hostBuilder, IEnumerable<string> exclusions = null, ILoggerFactory loggerFactory = null)
    {
...
        hostBuilder.Properties[LoggerName] = logger;

        hostBuilder.Configuration.AddSteeltoeConfigServer();
        hostBuilder.Services.AddMongoClient()
    }
}

Alternative Designs

We could make WebApplicationBuilder and HostApplicationBuilder explicitly implement IHostBuilder, but this breaks the API design of making the hosting code minimal, and running inline. It would cause a lot of confusion on when services, config, etc gets added in which order. For this reason, we don't want to keep using the IHostBuilder interface in new code.

Risks

N/A

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 6, ASP.NET added a WebApplicationBuilder "minimal hosting" API. This was a new, non-callback approach to the HostBuilder Generic Host API. In .NET 7, Extensions.Hosting added a similar "generic host" API that followed the same non-callback API design.

The problem is these two hosting APIs have the same members (mostly), but don't have a common base abstraction that libraries can add extension methods to. In the previous, callback API IHostBuilder was the interface libraries could extend and add their library-specific DI services, etc. to.

To enable this, we should add a general abstraction to these hosting builder APIs.

See the conversations at:

• Update the Worker template to use Host.CreateApplicationBuilder aspnetcore#47720 (comment)
• tweak that simplifies Worker startup code aspnetcore#43056

API Proposal

namespace Microsoft.Extensions.Hosting;

public interface IHostApplicationBuilder
{
    IDictionary<object, object> Properties { get; }

    IConfigurationBuilder Configuration { get; }  // can't be ConfigurationManager since that is in MS.Ext.Configuration and Hosting.Abstractions references Configuration.Abstractions. So need to pick between IConfiguration and IConfigurationBuilder
    IHostEnvironment Environment { get; }
    ILoggingBuilder Logging { get; }
    IServiceCollection Services { get; }

    IHost Build();  // See Note below on `Build()`
    void ConfigureContainer<TContainerBuilder>(IServiceProviderFactory<TContainerBuilder>factory, Action<TContainerBuilder>? configure = null) where TContainerBuilder: notnull;
}

Note on Build()

If we wanted to make this API work for all ApplicationBuilders like MauiAppBuilder and WebAssemblyHostBuilder, we would need to think about IHost Build(). Those 2 app models follow this same ApplicationBuilder pattern, but the things they build don't implement IHost. Options here are:

• Don't put Build() in the interface. But the name of the interface is "Builder", so it doesn't feel right to not have a Build method.
• For the app models that don't support IHost, they would throw NotSupported for this method. This is my recommendation.

API Usage

Using an existing extension method on IHostBuilder as an example, a new extension method could be written like:

public static class HostBuilderExtensions
{
    public static IHostBuilder AddSteeltoe(this IHostBuilder hostBuilder, IEnumerable<string> exclusions = null, ILoggerFactory loggerFactory = null)
    {
...
        hostBuilder.Properties[LoggerName] = logger;

        hostBuilder.Configuration.AddSteeltoeConfigServer();
        hostBuilder.Services.AddMongoClient()
    }
}

Alternative Designs

We could make WebApplicationBuilder and HostApplicationBuilder explicitly implement IHostBuilder, but this breaks the API design of making the hosting code minimal, and running inline. It would cause a lot of confusion on when services, config, etc gets added in which order. For this reason, we don't want to keep using the IHostBuilder interface in new code.

Risks

N/A

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

[eerhardt]

cc @davidfowl @halter73

[davidfowl]

We have to fix the Configuration API to allow reading it. Maybe we need an interface for the ConfigurationManager (this is why interfaces are great 😄).

[eerhardt]

We have to fix the Configuration API to allow reading it.

How do you feel about 2 properties?

public interface IHostApplicationBuilder
{
    IConfiguration Configuration { get; }
    IConfigurationBuilder ConfigurationBuilder { get; }

?

[davidfowl]

Doesn't feel good, but it's an option.

[eerhardt]

Updated the proposed API to include a new interface IConfigurationManager : IConfiguration, IConfigurationBuilder

[eerhardt]

cc @dotnet/area-extensions-configuration as well, since this proposal spans both Hosting and Configuration.

[steveharter]

Who is planning on driving and implementing this?

[ericstj]

@eerhardt @halter73 -- does this proposal imply libraries need to extend both IHostBuilder and IHostApplicationBuilder if they'd want to work in both minimal APIs and not?

[halter73]

The majority of libraries can get by just extending IServiceCollection. But if libraries need to also add config source and add services in a single method, or read the config/environment before adding services, they'll need to extend both IHostBuilder and IHostApplicationBuilder as you say.

I was able to update UseWindowsService and UseSystemd which previously targeted IHostBuilder to target IServiceCollection instead by reading the IHostEnvironment when constructing services rather than when adding them collection. I was hoping that most IHostBuilder extension methods could be updated to do something similar to avoid adding yet another builder interface.

If you extend just IHostBuilder, it will often still work with WebApplicationBuilder via the WebApplicationBuilder.Host property unless the extension method tries changing the host environment (e.g. by changing the content root) or calling Build() which is simply unsupported.

We could consider adding a similar IHostBuilder property to HostApplicationBuilder. We've already done most of the work to implement it because that's what's exposed via the "Microsoft.Extensions.Hosting" DiagnosticListener, but we decided against this in the original HostApplicationBuilder API review because of the inability to change certain host configuration keys like HostDefaults.ContentRootKey in ConfigureHostConfiguration or call Build() was clunky.

runtime/src/libraries/Microsoft.Extensions.Hosting/src/HostBuilder.cs

Lines 181 to 191 in 87189ec

	internal static DiagnosticListener LogHostBuilding(HostApplicationBuilder hostApplicationBuilder)
	{
	var diagnosticListener = new DiagnosticListener(HostBuildingDiagnosticListenerName);
	if (diagnosticListener.IsEnabled() && diagnosticListener.IsEnabled(HostBuildingEventName))
	{
	Write(diagnosticListener, HostBuildingEventName, hostApplicationBuilder.AsHostBuilder());
	}
	return diagnosticListener;
	}

runtime/src/libraries/Microsoft.Extensions.Hosting/src/HostApplicationBuilder.cs

Lines 307 to 314 in 87189ec

	// It's okay if the ConfigureHostConfiguration callbacks either left the config unchanged or set it back to the real ContentRootPath.
	// Setting it to anything else indicates code intends to change the content root via HostFactoryResolver which is unsupported.
	string? currentContentRootConfig = config[HostDefaults.ContentRootKey];
	if (!string.Equals(previousContentRootConfig, currentContentRootConfig, StringComparison.OrdinalIgnoreCase) &&
	!string.Equals(previousContentRootPath, HostBuilder.ResolveContentRootPath(currentContentRootConfig, AppContext.BaseDirectory), StringComparison.OrdinalIgnoreCase))
	{
	throw new NotSupportedException(SR.Format(SR.ContentRootChangeNotSupported, previousContentRootConfig, currentContentRootConfig));
	}