Support specifying host configuration via WebApplication.CreateBuilder

[davidfowl]

Background and Motivation

We've decided that it is not possible to mutate the host configuration (environment, application name, content root) after the call to WebApplication.Create/CreateBuilder this simplifies the implementation as we don't need to handle the environment changing arbitrarily as this issue describes. Today the only way to change host configuration is to specify them in a command line args format which isn't very ergonomic. We should add an API that lets the user configure host configuration specifically as part of the Create/CreateBuilder call.

Proposed API

namespace Microsoft.AspNetCore.Builder
{
    public class WebApplication
    {
-       public static WebApplicationBuilder CreateBuilder(string[]? args = null);
+       public static WebApplicationBuilder CreateBuilder();
+       public static WebApplicationBuilder CreateBuilder(string[] args);
+       public static WebApplicationBuilder CreateBuilder(WebApplicationBuilderOptions options);
    }

+   public sealed class WebApplicationBuilderOptions
+   {
+       public string[]? Args { get; init; } 
+       public string? EnvironmentName { get; init; }
+       public string? ApplicationName { get; init; }
+       public string? ContentRootPath { get; init; }
+ }
}

Usage Examples

var config = new WebApplicationOptions 
{
    Args = args,
    EnvironmentName = Environments.Staging,
    HostingStartupAssemblies = "Plugins",
};

var app = WebApplication.Create(options);

app.MapGet("/", (IHostEnvironment env) => env.EnvironmentName);

app.Run();

Alternative Designs

namespace Microsoft.AspNetCore.Builder
{
    public class WebApplication
    {
-       public static WebApplication CreateBuilder(string[]? args = null);
+       public static WebApplicationBuilder CreateBuilder();
+       public static WebApplicationBuilder CreateBuilder(string[] args);
+       public static WebApplicationBuilder CreateBuilder(IConfiguration configuration);
    }
}

Args will win to allow hosts like WebApplicationFactory to override application behavior. This is important for testing.

var config = new ConfigurationManager();
config.AddCommandLine(args);
config[HostDefaults.EnvironmentKey] = Environments.Development;
config[WebHostDefaults.HostingStartupAssembliesKey] = "Plugins";

var app = WebApplication.Create(config);

app.MapGet("/", (IHostEnvironment env) => env.EnvironmentName);

app.Run();

Risks

None.

PS: I removed these options from WebApplicationOptions because they are super advanced and are typically controlled by the environment. We can always add them but it seems like it might be overkill here. Open to suggestions of course.

public string? HostingStartupAssemblies { get; init; }
public string? HostingStartupExcludedAssemblies { get; init; }
public bool? PreventHostingStartup { get; init; }

Also I only changed CreateBuilder, and not Create because this is a more advanced scenario.

[jkotas]

Note that the specifying assemblies as strings in HostingStartupAssemblies is not trimming friendly. There is no good way for the trimmer to tell that it should keep the assemblies in this list around. It should be marked with RequiresUnreferencedCode attribute.

[davidfowl]

Note that the specifying assemblies as strings in HostingStartupAssemblies is not trimming friendly. There is no good way for the trimmer to tell that it should keep the assemblies in this list around. It should be marked with RequiresUnreferencedCode attribute.

That entire feature isn't trimming friendly, it's our version of startup hooks. We haven't done the work in .NET 6 to make ASP.NET Core trim friendly so these annotations will come en masse as part of .NET 7.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[davidfowl]

@mkArtakMSFT @pranavkm is the bot broken? Why does it send this message every time I change the API?

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[ghost]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[pranavkm]

API feedback -> WebApplicationOptions -> WebApplicationBuilderOptions. Discussion about args array being preferred over explicitly set properties. The behavior should be documented as part of the property description.