Make hosting configuration consistency

[davidfowl]

Right now we have a mix of config keys supported by the Hosting library. These grew organically and are inconsistent:

• Hosting:DetailedErrors - Show detailed errors for startup failures
• server or Hosting:Server - Specify which servers
• app or Hosting:App - Application where the startup is
• ASPNET_ENV or Hosting:Environment - The environment to run as (Development, Production etc)
• webroot - Webserver root, used by iis and static file servers

These values can be provided via Microsoft.AspNet.Hosting.json (soon to be hosting.json), command line options or environment variables.

Linux only supports _ as the separator for environment key separator so Hosting:Foo=1 turns needs to be specified as export Hosting__Foo=1.

Proposal:

Config file (Microsoft.AspNet.Hosting.json)

{
   "webroot": "wwwroot",
   "server" : "Microsoft.AspNet.Server.Kestrel",
   "app": "MyProjectReference",
   "environment": "Development",
   "detailedErrors": true
}

Command Line Options

Microsoft.AspNet.Hosting --server Microsoft.AspNet.Server.Kestrel --webroot "wwwroot" --app "MyProjectReference" --environment "Development" --detailedErrors true

The casing of --detailedErrors should really be detailed-errors, it's more unixy.

Environment variables

These are global enough that it makes sense to make them prefixed:

Prefix=ASPNET

ASPNET_WEBROOT=wwwroot
ASPNET_SERVER=Microsoft.AspNet.Server.Kestrel
ASPNET_APP=MyProjectReference
ASPNET_ENVIRONMENT=Development
ASPNET_DETAILED_ERRORS=true

Prefix=HOSTING

HOSTING_WEBROOT=wwwroot
HOSTING_SERVER=Microsoft.AspNet.Server.Kestrel
HOSTING_APP=MyProjectReference
HOSTING_ENVIRONMENT=Development
HOSTING_DETAILED_ERRORS=true

Problems, the low level hosting API (WebHostBuilder) lets users pass in IConfiguration directly, what values are we reading from this IConfiguration? Is it prefixed? Or should it assume the names are all top level?

I'd vote for top level names. Meaning that the above env variables would need to be transformed.

[davidfowl]

/cc @Tratcher @lodejard @DamianEdwards

[Tratcher]

What about server keys? e.g. server.urls?

Using different config key names from different sources will get very confusing and hard to document. Pick a naming scheme and using it everywhere would be the easiest for users to understand.

Otherwise to make this manageable on our end I think you'd need to specify a prefix to prepend when loading a config source like changing https://github.com/aspnet/Hosting/blob/dev/src/Microsoft.AspNet.Hosting/WebApplication.cs#L44-L48 to

                .AddJsonFile(configFilePath, optional: true, prefix: "hosting")
                .AddEnvironmentVariables()
                .AddCommandLine(args, prefix: "hosting")

so your json file containing:

{
   "webroot": "wwwroot"
}

would get loaded as "hosting:webroot"="wwwroot".

[davidfowl]

How we implement it is irrelevant. The fact that we use the config API is an implementation detail. Adding an API for that is fine but I'm more concerned about the horribly inconsistent values we have today. That plus the fact that _ is the only thing that works in env variables in *nix and the fact that top level files specific to hosting (and the exe) shouldn't have a prefix. It's like saying git git-commit

[davidfowl]

@divega What do you think about the configuration API to allow prepending a prefix?

[divega]

It depends. I couldn't parse from the thread whether this is just a prefix to apply to every key or a parent path, e.g. are you trying the environment variable to be HOSTING_WEBROOT or HOSTING__WEBROOT? For *nix we are using double _ as the delimiter.

[lodejard]

the environment config provider already enables you to scope to a prefix, so "ASPNET_" or "HOSTING_" can be done today

https://github.com/aspnet/Configuration/blob/dev/src/Microsoft.Extensions.Configuration.EnvironmentVariables/EnvironmentVariablesConfigurationProvider.cs#L23

when the user passes in IConfiguration directly they can call GetSection("Hosting") if they don't want the values to be top-level in their file. so always looking for top-level keys in the hosting code seems fine.

+1 for all this

[Tratcher]

@BillHiebert @rustd FYI

[poke]

The inconsistencies were bothering me for a while already, thanks for this change!