search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.62k stars 25.3k forks source link

Document how Configuration merges arrays/dictionary #27620

Open Siphonophora opened 1 year ago

Siphonophora commented 1 year ago

I have been trying to troubleshoot issues with arrays being merged between appsettings.json and the environments specific file and I finally found what is going on explained here https://github.com/dotnet/runtime/issues/36569#issuecomment-1107003676. Given this is expected behavior AND its counterintuitive it really needs to be documented here.

I think docs need to cover 2 things.

  1. The way array indexes and dictionary keys are merged. Show examples of the merging.
  2. Provide some suggestion for how to work around this when appsettings.json needs to have more items in an array than some of the other environments (or different dictionary keys).
    1. The option I saw the most is to delimit a string and split it.
    2. Delimiting doesn't work if its an array of objects. In that case I think its simplest in the config to point to another file which you can de-serialize.

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

Siphonophora commented 1 year ago

btw, this post https://levelup.gitconnected.com/overriding-an-array-configuration-object-4d93470e97d0 has links to a bunch of github/stackoverflow discussions about this being confusing.

Rick-Anderson commented 1 year ago

I have been trying to troubleshoot issues with arrays being merged between appsettings.json and the environments specific file

Like appsettings.json and appsettings.Production.json? I'll add item 1 but item 2 is very niche. Thanks for bringing this to our attention with links to solutions.

Siphonophora commented 1 year ago

Like appsettings.json and appsettings.Production.json? Yeah

For work arounds, I was just tossing out options. Understood it needs to be broadly applicable.

Maybe in some cases the best guidance is not to put array or dictionary config in appsettings.json at all. If you want to use that kind of config (and that seemed pretty common from the links in that blog post) then you should only configure it in appsettings.[environment].json.