Aspnetcore.docs: Configuring with Environment Variables

Created on 5 Dec 2017 · 11Comments · Source: dotnet/AspNetCore.Docs

New topic suggestion

I'd like to propose some basic documentation be added around using environment variables for configuration that describes things such as the format of the key to be used.

I recently experience an issue around changes between running on Debian Stretch vs Debian Jessie that I documented here: https://www.stevejgordon.co.uk/asp-net-core-gotchas-number-1

I could not find any existing documentation to specifically how environment variables are expected to be set.

Possibly this extends https://github.com/aspnet/Docs/blob/master/aspnetcore/fundamentals/configuration/index.md or is a sub-page linked from the index.

If this sounds useful I would like to try to find time to support outlining a more detailed contents for this topic.

Help wanted P3

Source

stevejgordon

All 11 comments

I could not find any existing documentation to specifically how environment variables are expected to be set.

Coverage for setting them for the environment is in the Working with multiple environments topic, so there is some coverage on what to do on various platforms and with VS (but not VSC :cry:).

I'd point out tho that setting env vars generally might be better over in the .NET Core docs, as it feels more like a tooling/platform area activity rather than a web app programming activity.

btw -- I was just wondering something: https://github.com/dotnet/cli/issues/8179

guardrex on 7 Dec 2017

Thanks for replying @guardrex.

Coverage for setting them for the environment is in the Working with multiple environments topic, so there is some coverage on what to do on various platforms and with VS (but not VSC :cry:).

That documentation seems to only focus on setting the ASPNETCORE_ENVIRONMENT environment variable and not overriding/setting custom configuration using environment variables.

I'd point out tho that setting env vars generally might be better over in the .NET Core docs, as it feels more like a tooling/platform area activity rather than a web app programming activity.

In my case I'm thinking about setting values which I can then access via IOptions. That feels ASP.NET specific. I'm don't think it would be a big document (any maybe just needs clarifying on the existing docs). Mostly I think the use of double underscore vs colon needs to be promoted as the best (safest) practice since it works on any OS. @DamianEdwards did point out on the community standup that there a one line reference to this on https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration within the Configuration considerations section. I'm wondering if it can be called out more prominently.

btw -- I was just wondering something: dotnet/cli#8179

This sounds interesting. In our case I'm not sure if it would totally help. We're generally setting env vars when starting containers using docker-compose or some Cloud based mechanism. This allows instances to use the same image but run with different configuration for different deployment environments.

So in this issue case I was thinking more about the advice of using __ as a general rule when setting values, however you choose to do that.

stevejgordon on 7 Dec 2017

use of double underscore vs colon needs to be promoted as the best (safest) practice since it works on any OS

That would be a significant guidance shift. However, taking that bullet point that pertains to the use of the double-underscore and making a dedicated section out of it might be welcome. SGTM

guardrex on 7 Dec 2017

Fair enough on the guidance. If the docs can make the underscore option a little more obvious hopefully that will help developers pick the correct option.

stevejgordon on 11 Dec 2017

@guardrex I assume this would be closed at the same time #4968 gets closed. Is that correct?

isaacrlevin on 14 Mar 2018

I think so ... I marked that issue as a dup of (or very closely related to) this one. @rachelappel has these, so she'll take care of it.

guardrex on 14 Mar 2018

If @rachelappel is working on them, why are they up-for-grabs :)

isaacrlevin on 14 Mar 2018

That should be an oversight. We usually pull the label when the issue is assigned. However, I'll let her do that, since I'm not sure what the status is on this one. I just know it isn't on my plate at the moment. 😅

guardrex on 14 Mar 2018

@isaac2004 I'll be unassigning that one. It's really up for grabs.