[API Proposal]: Add IConfiguration.HasChildren

[layomia]

Background and motivation

We should add a new HasChildren property to IConfiguration. An implementation given existing APIs might look like this:

public static bool HasChildren(IConfiguration configuration)
{
    foreach (IConfigurationSection section in configuration.GetChildren())
    {
        return true;
    }
    return false;
}

This implementation makes allocations which is not ideal. We could get better perf with a new API with a more optimal framework implementation.

API Proposal

namespace Microsoft.Extensions.Configuration
{
    public interface IConfiguration
    {
+        public bool HasChildren { get; }
    }
}

API Usage

A primary user of this feature would be the configuration binding source generator. Sample code it would generate:

private static void BindCore(IConfiguration configuration, MyClass obj)
{
    ThrowIfNull(obj);

    if (configuration["MyString"] is string stringValue0)
    {
        obj.MyString = stringValue0;
    }

    IConfigurationSection section2 = configuration.GetSection("MyList");
    if (section2.HasChildren)
    {
        List<int> temp3 = obj.MyList;
        temp3 ??= new List<int>();
        BindCore(section2, ref temp3);
        obj.MyList = temp3;
    }

    IConfigurationSection section4 = configuration.GetSection("MyDictionary");
    if (section4.HasChildren)
    {
        Dictionary<string, string> temp5 = obj.MyDictionary;
        temp5 ??= new Dictionary<string, string>();
        BindCore(section4, ref temp5);
        obj.MyDictionary = temp5;
    }

    // Repeat for every object or collection property on MyClass
  }

We see that the binding performance would improve with a more optimal implementation, particularly for large object graphs.

cc @tarekgh @eerhardt @davidfowl @dotnet/area-extensions-configuration

Tagging subscribers to this area: @dotnet/area-extensions-configuration
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

We should add a new HasChildren property to IConfiguration. An implementation given existing APIs might look like this:

public static bool HasChildren(IConfiguration configuration)
{
    foreach (IConfigurationSection section in configuration.GetChildren())
    {
        return true;
    }
    return false;
}

This implementation makes allocations which is not ideal. We could get better perf with a new API with a more optimal framework implementation.

API Proposal

namespace Microsoft.Extensions.Configuration
{
    public interface IConfiguration
    {
+        public bool HasChildren { get; }
    }
}

API Usage

A primary user of this feature would be the configuration binding source generator. Sample code it would generate:

private static void BindCore(IConfiguration configuration, MyClass obj)
{
    ThrowIfNull(obj);

    if (configuration["MyString"] is string stringValue0)
    {
        obj.MyString = stringValue0;
    }

    IConfigurationSection section2 = configuration.GetSection("MyList");
    if (section2.HasChildren)
    {
        List<int> temp3 = obj.MyList;
        temp3 ??= new List<int>();
        BindCore(section2, ref temp3);
        obj.MyList = temp3;
    }

    IConfigurationSection section4 = configuration.GetSection("MyDictionary");
    if (section4.HasChildren)
    {
        Dictionary<string, string> temp5 = obj.MyDictionary;
        temp5 ??= new Dictionary<string, string>();
        BindCore(section4, ref temp5);
        obj.MyDictionary = temp5;
    }

    // Repeat for every object or collection property on MyClass
  }

We see that the binding performance would improve with a more optimal implementation, particularly for large object graphs.

Alternative Designs

No response

Risks

No response

Author:	layomia
Assignees:	layomia
Labels:	api-suggestion, area-Extensions-Configuration
Milestone:	8.0.0

[tarekgh]

I think this needs to be an extension method on the IConfiguration and not extending the original interface. Right? Can't we just add this to the internal extensions we have here https://source.dot.net/#Microsoft.Extensions.Configuration/InternalConfigurationRootExtensions.cs,13? I know we need to have a public way to access it though.

[layomia]

I think this needs to be an extension method on the IConfiguration and not extending the original interface.

I know we need to have a public way to access it though.

Would we be establishing a new pattern for APIs on the type?

Having it be a property on the type itself seemed natural to me since we expect this to be a cheap/cached check. I did a quick scan of what an implementation would look like to verify this assumption, but I'll have to dive a bit deeper to be sure.

We could also consider optimizing GetChildren(); there's a lot of LINQ usage in the implementation.

[eerhardt]

In order for this to actually be beneficial, it would need to be a property on the interface. An extension property could only hard-code our own configuration types - ConfigurationRoot, ConfigurationManager, etc. For other IConfiguration types, it would need to call GetChildren().Any().

We could also consider optimizing GetChildren(); there's a lot of LINQ usage in the implementation.

Note that in this case we are eagerly building the full list (which we need to do for the reason in the comment):

runtime/src/libraries/Microsoft.Extensions.Configuration/src/InternalConfigurationRootExtensions.cs

Lines 38 to 39 in 967250c

	// Eagerly evaluate the IEnumerable before releasing the reference so we don't allow iteration over disposed providers.
	return children.ToList();

[tarekgh]

it would need to be a property on the interface.

Is it possible we can extend this interface? note this interface is supported on the .NET Framework which adding anything there will be a breaking change.

[eerhardt]

We would either do it the way we IMemoryCache.GetCurrentStatistics:

runtime/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/IMemoryCache.cs

Lines 34 to 40 in 967250c

	#if NET6_0_OR_GREATER
	/// <summary>
	/// Gets a snapshot of the cache statistics if available.
	/// </summary>
	/// <returns>An instance of <see cref="MemoryCacheStatistics"/> containing a snapshot of the cache statistics.</returns>
	MemoryCacheStatistics? GetCurrentStatistics() => null;
	#endif

Or we could introduce a new interface that had the new property on it. Then an extension method could check for the interface and cast to it. And if the IConfiguration didn't implement the interface, it could fall back to GetChildren().Any(). That would still work on .NET Framework.

[davidfowl]

Help me understand the case this is optimized for? For a missing section the IConfigurationSection.Value is null, so

runtime/src/libraries/Microsoft.Extensions.Configuration.Abstractions/src/ConfigurationExtensions.cs

Line 78 in 967250c

public static bool Exists([NotNullWhen(true)] this IConfigurationSection? section)

would work right? If there is a section then we're going to enumerating it anyways.

[layomia]

I wasn't aware of that implementation. I also used section.GetChildren().Any() initially but the feedback is that we want to avoid LINQ in the source gen implementation.

If there is a section then we're going to enumerating it anyways.

I guess it would be helpful in the cases where there are no children so we avoid allocating a section.

[davidfowl]

I wasn't aware of that implementation. I also used section.GetChildren().Any() initially but the feedback is that we want to avoid LINQ in the source gen implementation.

We should use Exists in the source generator.

I guess it would be helpful in the cases where there are no children so we avoid allocating a section.

It'd only be helpful in the case where there was a section, but it was empty.

In the latter case this looks like it can be optimized to avoid allocations for empty sections.