Difference in behavior between .NET and Microsoft schemas with configuration merging

[CuddleBunny]

This isn't necessarily an issue, but it should probably be called out somewhere: when switching from the .NET schema to the Microsoft schema you lose the ability to spread definitions across multiple configuration files (ie. appsettings.json and appsettings.Prod.json) because feature_management:feature_flags is an array which causes additional configuration sources to overwrite the original. This isn't the case with the .NET schema because the collection is an object and merges fine.

[CuddleBunny]

This bit me again today, so I'll illustrate further:

appsettings.json

{
  "feature_management": {
    "feature_flags: [
      {
        "id": "SameForAllEnvironmentsThing",
        "enabled": true
      },
      {
        "id": "SameForAllEnvironmentsThing2",
        "enabled": true
      }
    ]
  }
}

appsettings.Prod.json

{
  "feature_management": {
    "feature_flags: [
      {
        "id": "ProdOnlyThing",
        "enabled": true
      }
    ]
  }
}

After these are loaded into configuration, the resulting feature_flags array contains only the two items after merging when all three are expected:

[ { id = "ProdOnlyThing" }, { id = "SameForAllEnvironmentsThing2" } ]

[rossgrambo]

Hey @CuddleBunny, thank you for calling this out and following up on it.
 
It's unfortunate that this change to unify our libraries caused this to work differently.

The issue with Configuration merging is discussed here. Sadly, it's upstream of FeatureManagement- as this library reads whatever is made available by IConfiguration.

Theres two workarounds I'm aware of:

Define your own IFeatureDefinitionProvider

I know this could solve the issue if you manually read the files and merge them how you see appropriate. Our default implementation reads from IConfiguration but you don't have to in your version.

It might be possible to have your implementation call each JsonConfigurationProvider within the Configuration separately so you can handle the merge yourself and don't have to re-read these files. If this is possible and not too heavy it could be something we consider adding to the default IFeatureDefintionProvider. But I think that's unlikely because there's not one way to merge that works for everyone.

:# syntax (Not recommended)

Using :# to override arrays appropriately.
When defining an array in json to be used in IConfiguration, you can define it like:

"feature_management": {
  "feature_flags:0": {
    "id": "OnTestFeature",
    "enabled": true
  }
}

In your example, you could define your appsettings.prod.json as

{
  "feature_management": {
    "feature_flags:2": {
      "id": "ProdOnlyThing",
      "enabled": true
    }
  }
}

Unfortunately, this is finicky to line things up when you're trying to override correctly.

If your only goal is to merge I believe you start at a large number (like :1000) in all of your prod flags and they would always append to the end of the other flags. This is not an intended feature of our library so there's no guarantee that it'll continue to work but it seems to work for me at first glance.

[CuddleBunny]

I've considered the IFeatureDefinitionProvider route already and will likely take that path. We should close this issue, but it could probably be called out in the docs somewhere as a possible gotcha, especially because the default dotnet templates have configuration per environment built in so it's widely used.

[pinkfloydx33]

@CuddleBunny did you ever come up with something reasonable?

[CuddleBunny]

@CuddleBunny did you ever come up with something reasonable?

For the moment I've removed all feature flags from appsettings.json and have the full list duplicated in every environment specific configuration. I haven't had the bandwidth to write the custom IFeatureDefinitionProvider but when I do I'll be sure to post an example here. There also shouldn't be any reason why I couldn't release the new provider as a nuget package for others to use.

[jimmyca15]

@rossgrambo provided a solution using different offsets in the feature flag array across different appsettings.json file. He mentioned not recommended, but I actually think this is a reasonable approach. If you define the flags in your appsettings.json with some high offset, which is different in each file, there should be no collisions. This saves the effort of having to create a custom IFeatureDefinitionProvider.

This is a bit of a battle with the .NET configuration system which doesn't allow different configuration providers (e.g. two different json files, or a json file + app configuration) to know about each other and adjust accordingly.

[pinkfloydx33]

I fortunately only need this for development setups where I provide the settings packaged in a docker image and devs might override them. No azure app config involved.

Based on the suggestion above, I actually discovered that due to the way this library reads the configuration (it just walks the children directly) , that you can use named keys instead of integers for the feature flags:

{
   "feature_management": {
       "feature_flags:named": {

      }
  }
}

This is much easier to reason about and remember, if the goal is layering. I wouldn't do this in production but like I said my target is local development scenarios so this works fine.

Unfortunately it stops there, as the feature definition provider doesn't work quite the same for variants. In that case it tries to parse the key as an integer and if it fails it will skip the variant section.

[jimmyca15]

Interesting, I am thinking about the difference in support there.

[pinkfloydx33]

Yeah I accidentally discovered that, but then dug into the source a little.

It totally falls apart if anything is coming from Azure AppConfig since the provider converts the data into arrays (and thus numbered keys) and there's no way to know what order the features or variants are going to come from AAC. Use of arrays is unfortunate with the way the dotnet configuration provider performs configuration layering

[abatishchev]

I'm adopting FM in my ASP.NET Core app and this issue worries me. I basically have 2 requireements:

1. Define features in the root config (appSettings.json)
2. Be able to turn them on and off (i.e. override) based in sub-configs (cloud, environment, region)

Would I be able to achieve the latter using the default format which is an array?

For the named keys "hack", I found that id is still mandatory, i.e.:

"feature_management": {
  "feature_flags:FooBar": {
    "id": "FooBar",
    "enabled": true,
    "telemetry": {
      "enabled": true
    }
  }
}

Otherwise, it fails to bind and GetFeatureDefinitionAsync returns nothing.

[jimmyca15]

@abatishchev so you are only using json files for configuration?

[abatishchev]

@jimmyca15 yes. the underlying hosting platform is Service Fabric. But it's running my app as a guest executable (simply starts it up and makes sure it doesn't go down) so the app's code doesn't have any dependencies on SF, uses the standard ASP.NET tooling: ILogger, IOptions, DI, etc.

I can share more details internally.

[jimmyca15]

@zhiyuanliang-ms @rossgrambo @amerjusupovic

I think what we need to do here is break down .NET's IConfiguration system and merge the arrays ourselves via

IConfigurationRoot.Providers (link)

The App Configuration configuration provider does something similar (link).

With this change, one would have to duplicate the entire flag definition across json files in order to override, but it does mean that override will work as expected. Last flag definition to be read in wins.