Repository navigation
Add BinderOption to allow callers to specify that configuration binding should throw an exception upon any failure. #36015
Description
UPDATED PROPOSAL
Background and Motivation
The configuration binding system provided by Microsoft.Extensions.Configuration currently does not throw any kind of exception should there be any issue binding configuration data to a model object. Scenarios such as a key missing from a configuration provider, or a model object not being updated to provide access to a new configuration key can often result in difficult to diagnose run-time errors, some of which might not be caught until a deployment, as one of the few differences between testing and production environments are configuration values.
There would be value in providing users of the configuration system a mechanism to make model binding in either direction an exception-throwing event to make it more immediately apparent when issues arise due to configuration mismatches.
Proposed API
Create a new exception Microsoft.Extensions.Configuration.ConfigurationException. As much as possible, this exception should be designed to include as much information as possible based on the context in which it is throw. Given the proposals below, the exception should, at a minimum, always include the name of the configuration key and (when possible)/or (when not) the model property that was being bound at the time the exception was thrown.
Add two new properties to the Microsoft.Extensions.Configuration.BinderOptions class:
public class BinderOptions
{
/// <summary>
/// When false (the default), the binder will only attempt to set public properties.
/// If true, the binder will attempt to set all non read-only properties.
/// </summary>
public bool BindNonPublicProperties { get; set; }
+ /// <summary>
+ /// If set to true, the configuration system would throw a `ConfigurationException` if, during configuration binding, a
+ /// configuration key is found for which the provided model object does not have an appropriate property which matches
+ /// the keys name. Note: appropriate property here refers to a property that is eligible to be bound to (for example, a
+ /// private property would not be considered an `eligible` target property unless
+ /// </summary>
+ public bool ErrorOnPropertyMissing { get; set; }
+ /// <summary>
+ /// If set to true, the configuration system would throw a `ConfigurationException` if, during configuration binding, a
+ /// property is found on a target model object which does not have a corresponding configuration key provided by any
+ /// configuration providers. Default value is false.
+ /// </summary>
+ public bool ErrorOnKeyMissing { get; set; }
}Usage Examples
Below is an example when BinderOptions is being used alongside the Microsoft.Extensions.Options package. The usage would be the same for any other location where BinderOptions can be provided as an argument.
services.AddOptions<RequestHandlingOptions>().Bind(Configuration.GetSection("RequestHandlingOptions"), options =>
{
options.BindNonPublicProperties = true;
options.ErrorOnKeyMissing = true;
options.ErrorOnPropertyMissing = true;
});Alternative Designs
I had considered including a 3rd flag as a new property: BinderOptions.ErrorOnConfigurationMismatch which would perhaps throw an exception in both cases proposed above, and/or additionally in other cases (such as model property count/configuration key count mismatch, which may or may not imply the above scenarios in some cases). Ultimately though I felt a simpler approach was best to start.
Or instead of adding the two properties above, add just one properties that controls throwing on all mismatches instead.
public class BinderOptions
{
/// <summary>
/// When false (the default), the binder will only attempt to set public properties.
/// If true, the binder will attempt to set all non read-only properties.
/// </summary>
public bool BindNonPublicProperties { get; set; }
+ /// <summary>
+ /// If set to true, the configuration system would throw a `ConfigurationException` if, during configuration binding, a
+ /// configuration key is found for which the provided model object does not have an appropriate property which matches
+ /// the keys name; or if a configuration property is found without a matching key.
+ /// </summary>
+ public bool ErrorOnConfigurationMismatch { get; set; }
}Risks
As these flags would be disabled by default, the existing behavior of the configuration binding process would not change. However, developers should be encouraged to thoroughly test their configuration management systems when enabling these flags, given the environment-dependent nature of configuration management and the potential impact of the change should there be any issues with a systems configuration.
ORIGINAL POST
Is your feature request related to a problem? Please describe.
Currently, when using configuration binding, in the event that a property does not get bound (either because there's a missing entry in the configuration file or a missing property on the class being bound to), the binder simply defaults to null for that property. This results in run-time null exceptions if there is a configuration issue.
Describe the solution you'd like
I propose we add an optional setting in the new BinderOptions class which allow callers to specify that in the event of a failure to properly bind every configuration option, to throw an exception rather than passively set property values to null.
An optional extension of this idea would be to also allow callers to specify custom validators for specific configuration values. For example, being able to annotate the POCO that a configuration file is being bound to such that something like a Connection String could have a custom validator called on it to make sure all the required arguments are contained in the string, the database is reachable, etc.
Describe alternatives you've considered
The alternative is to use something like an IStartupFilter to manually check all your configuration parameters validity during application start-up. This is tedious and error-prone, and results in application level code having to validate behaviors provided by framework level code, mixing concerns.
Additional context
I believe this feature will add a lot of value at relatively low cost. It's much easier to find misconfiguration errors if start-up fails because of app misconfiguration, rather than having to track down unexpected null exceptions thrown from some piece of code using configuration values.
It looks like there's been some work/discussion on this front in other forms (issue dotnet/extensions#459 and issue dotnet/extensions#763), but those are more focused on the larger problems of IOption and custom validators. Perhaps this issue can focus solely on establishing a starting point via making Bind() throw on error an option.
I'd be more than happy to put up an initial PR to explore this further.
Activity
[-]Add BinderOption to allow callers to specify that configuration binding should thrown an exception upon any failure.[/-][+]Add BinderOption to allow callers to specify that configuration binding should throw an exception upon any failure.[/+]BlacKCaT27 commentedon Dec 12, 2019
@Pilchie I'm just a fan of .net core who wants to make a contribution, not privy to the teams plans, but I don't want to put up a PR that has no chance of being merged if what I submit goes against whatever plan your team has on this topic. Is there already something in the works on this front?
maryamariyan commentedon Oct 1, 2020
@BlacKCaT27 thanks for the issue. We usually stay away from throwing first hand exceptions, but since this is configurable and disabled by default this feature makes sense.
cc: @davidfowl
To satisfy this issue there needs to be a new API proposal introduced in configuration binding.
The best next step on this would be to prepare the API proposal, usage, etc. in the issue page here (following https://github.com/dotnet/runtime/blob/master/docs/project/api-review-process.md).
davidfowl commentedon Oct 2, 2020
It depends on how you bind, it won't fail at startup, it'll fail when you try to resolve the options.
maryamariyan commentedon Oct 6, 2020
Related to closed dupe: #36129 and #36502
BlacKCaT27 commentedon Oct 8, 2020
Thank you very much for the update. I'll try to get a proposal together this weekend.
BlacKCaT27 commentedon Oct 11, 2020
Background and Motivation
The configuration binding system provided by
Microsoft.Extensions.Configurationcurrently does not throw any kind of exception should there be any issue binding configuration data to a model object. Scenarios such as a key missing from a configuration provider, or a model object not being updated to provide access to a new configuration key can often result in difficult to diagnose run-time errors, some of which might not be caught until a deployment, as one of the few differences between testing and production environments are configuration values.There would be value in providing users of the configuration system a mechanism to make model binding in either direction an exception-throwing event to make it more immediately apparent when issues arise due to configuration mismatches.
Proposed API
Create a new exception
Microsoft.Extensions.Configuration.ConfigurationException. As much as possible, this exception should be designed to include as much information as possible based on the context in which it is throw. Given the proposals below, the exception should, at a minimum, always include the name of the configuration key and (when possible)/or (when not) the model property that was being bound at the time the exception was thrown.Add two new properties to the
Microsoft.Extensions.Configuration.BinderOptionsclass:BinderOptions.ErrorOnKeyMissing- boolean - If set to true, the configuration system would throw aConfigurationExceptionif, during configuration binding, a property is found on a target model object which does not have a corresponding configuration key provided by any configuration providers. Default value is false.BinderOptions.ErrorOnPropertyMissing- boolean - If set to true, the configuration system would throw aConfigurationExceptionif, during configuration binding, a configuration key is found for which the provided model object does not have an appropriate property which matches the keys name. Note: appropriate property here refers to a property that is eligible to be bound to (for example, a private property would not be considered aneligibletarget property unlessBinderOptions.BindNonPublicPropertieswere set to true).Usage Examples
Below is an example when
BinderOptionsis being used alongside theMicrosoft.Extensions.Optionspackage. The usage would be the same for any other location whereBinderOptionscan be provided as an argument.Alternative Designs
I had considered including a 3rd flag as a new property:
BinderOptions.ErrorOnConfigurationMismatchwhich would perhaps throw an exception in both cases proposed above, and/or additionally in other cases (such as model property count/configuration key count mismatch, which may or may not imply the above scenarios in some cases). Ultimately though I felt a simpler approach was best to start.Risks
As these flags would be disabled by default, the existing behavior of the configuration binding process would not change. However, developers should be encouraged to thoroughly test their configuration management systems when enabling these flags, given the environment-dependent nature of configuration management and the potential impact of the change should there be any issues with a systems configuration.
11 remaining items
safern commentedon Feb 1, 2021
The thing that it's making me doubt about that approach is that if I want the system to throw about any unknown configuration, I would have to add the attribute to all the keys? Maybe we could come up with a behavior where if you add it to the class it should throw for all the keys under that class, but if you have a subclass then you would end up annotating all classes, so in that case a switch would be simpler. So I think having the switch for an all or nothing behavior is helpful and then the attribute for a granular situation?
BlacKCaT27 commentedon Feb 1, 2021
True, though I think at that point it depends more on the use case. I could see some scenarios where there's only a couple fields where I want this attribute (so an unmatched configuration throws, like a connection string) but for others I don't care.
What if, like you suggest, a switch for all-or-nothing behavior gets added, but then the attribute can be used to configure the systems reaction. Like, instead of the switch saying "do I or do I not throw when there's a problem", the switch becomes "check for required configuration attributes" and then the attribute can have a parameter list that describes what should happen on a failure. That way you could make the attribute more useful by giving it optional params like a default value to assign alongside a flag dictating whether or not to throw.
Going this route you could then safely default the switch to On, since it would be inert until someone used
ConfigurationRequiredAttribute. Then setting the switch to Off could be used like a debug control if a developer needs to disable it for any reason.safern commentedon Feb 1, 2021
While I understand the intent of what you describe above I think not depending on attributes and being able to bind with validation for missing Properties by just turning on a switch is a really good thing to have. Then the attributes could be a separate configuration that doesn't depend on the switch where you can granularly fail for missing properties/keys and also configure the default value for a required configuration.
Don't you think it is still valuable for complicated configurations to instead of having to throw an attribute on all properties, to just turn on a switch to get missing properties validation?
BlacKCaT27 commentedon Feb 1, 2021
safern commentedon Feb 1, 2021
Awesome. Thanks for the discussion. Feel free to open a separate issue for the attribute addition where we can discuss the design of it.
Are you interested on tackling this issue?
BlacKCaT27 commentedon Feb 2, 2021
SteveDunn commentedon May 23, 2021
I'd be happy to take this one on. My last PR (#52514) was closed as there was not enough information provided before being marked up-for-grabs, and hence the .net team will be doing it themselves at some point.
So it'd make sense for me to start another easy-ish task from a somewhat familiar area of the repo.
maryamariyan commentedon May 25, 2021
@SteveDunn sounds good.
SteveDunn commentedon Jun 8, 2021
I created a PR for this: #53852