[API Proposal]: The Configuration Binding Generator should be able to understand different common formats of boolean values

[baronfel]

Background and motivation

Today the Source-Generated Configuration binding supports only values that satisfy bool.Parse - but especially in the space of environment variables and user-facing config files there are many formats that are quite common:

• 1 / 0
• y / n
• yes / no

The dotnet CLI has broad support for these in its current hand-rolled configuration/env var handling, but we're investigating unifying on IConfiguration (and binding generation) as part of an overall road to AOT and this would be an unfortunate take-back for us. I'm sure we could hand-roll something while still being based on IConfiguration, but the generator is such a nice thing to reach for!

API Proposal

There should be some way to signal on a field/property basis that a boolean field/property supports more than just true/false as signal values - perhaps an attribute, or some way to 'tag' the field/property with a converter like JSON Source Generation can do.

API Usage

/// <summary>
/// Configuration settings that control the CLI's user interface and interaction behavior.
/// </summary>
public sealed class CliUserExperienceConfiguration
{
    /// <summary>
    /// Gets or sets whether telemetry collection is disabled.
    /// Mapped from DOTNET_CLI_TELEMETRY_OPTOUT environment variable.
    /// </summary>
    [BooleanBinding(AllowedForms = Boolean.TrueFalse | Boolean.YesNo | Boolean.ZeroOne)]
    public bool TelemetryOptOut { get; set; } = CompileOptions.TelemetryOptOutDefault;

    /// <summary>
    /// Gets or sets whether to suppress the .NET logo on startup.
    /// Mapped from DOTNET_NOLOGO environment variable.
    /// </summary>
    [BooleanBinding(AllowedForms = Boolean.TrueFalse | Boolean.YesNo | Boolean.ZeroOne)]
    public bool NoLogo { get; set; } = false;

    /// <summary>
    /// Gets or sets whether to force UTF-8 encoding for console output.
    /// Mapped from DOTNET_CLI_FORCE_UTF8_ENCODING environment variable.
    /// </summary>
    [BooleanBinding(AllowedForms = Boolean.TrueFalse | Boolean.YesNo | Boolean.ZeroOne)]
    public bool ForceUtf8Encoding { get; set; } = false;

    ....
}

Alternative Designs

I suppose for our use case specifically we could have a custom type that we completely control the parsing of that could be coercible to bool for usage in the codebase?

Risks

No response

[dotnet-policy-service]

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

[tarekgh]

I believe this functionality belongs to the CLI. The configuration source generator should focus solely on supporting configuration binding. The only aspect relevant to the source generator is handling the binding of different Boolean value representations.

The rest of the proposal should be handled by the CLI. Here's how I envision the flow:

• The user defines their configuration for the CLI.
• The CLI retrieves the configuration values and reacts to the values.
• The configuration source generator performs the binding—independent of the CLI or any other component.

Let's use this issue for configuration binding, and I suggest you open issue for CLI to decide how to do the other parts.

[baronfel]

Making sure I understand the separation of concerns correctly here:

• Typed configuration models should be comprised of actual CLR types like bool
• The providers that the CLI configures on the builder are then responsible for mapping nonstandard values into true/false during population of the configuration sources so that binding only has to care about valid values
• there's a potential enhancement to the configuration binder for the boolean parsing specifically to potentially handle a broader range of truthy/falsy values

Is that correct? if so, that's great - I think there's a need for some flexibility on booleans at binding time because you're separated from the source of the value by that point. You don't know at value-ingestion time if the environment value 1 is meant to signal a boolean. In fact, for boolean flags and environment variables specifically, even the presence of the env var (notwithstanding any value) is a 'true' signal in some scenarios.

[lindexi]

My CommandLine lib support the follow value as bool value:

1, true, yes, on,
0, false, no, off.

See https://github.com/dotnet-campus/DotNetCampus.CommandLine/blob/487902f67b02b58da754a26bac9cb1812c5d8a95/src/DotNetCampus.CommandLine/CommandLinePropertyValue.cs#L43-L63

And I agree with @tarekgh , "I believe this functionality belongs to the CLI."

[tarekgh]

@baronfel I think you got it right. the CLI can still handle the Boolean case by reading the configuration value as string and then check whatever values want to support (Y, N, yes, no, 1, 0...etc.). We do that in the runtime today.

runtime/src/libraries/System.Net.Http/src/System/Net/Http/BrowserHttpHandler/BrowserHttpHandler.cs

Line 605 in f1f9934

if (str == "1" || str.Equals("true", StringComparison.OrdinalIgnoreCase))

Please open this issue to the CLI and if the CLI cannot handle reading different Boolean values, we can talk about enhancing the binder to support more Boolean values later.