Runtime: Proposal: add GetEnvironmentVariableAsBool to netstandard

[danmosemsft]

@diddledan commented on Tue Dec 19 2017

Currently the dotnet cli has a function which is located at: src/Microsoft.DotNet.Cli.Utils/EnvironmentProvider.cs Line 106

I think it would be useful to consider this functionality for inclusion into the System.Environment namespace.

This issue is to raise the idea and garner discussion. I do not believe it would conflict with anything already present, though I've not performed a thorough examination to prove it.

---

@danmosemsft commented on Wed Dec 27 2017

@diddledan the right place to propose new API is the corefx repo...

[diddledan]

thanks for moving this to the correct place, @danmosemsft :-)

Rationale and Usage

Dotnet-cli includes a function to marshal an environment variable's value from a string into a boolean value if it conforms to a truthy or falsey, such as: true (any case), Yes (any case), and 1 for truthy; and false (any case), No (any case), and 0 for falsy. There is no current provision in the System.Environment namespace for a similar capability, and so implementations will need to create the function in each project that requires it. As this seems to be a potentially beneficial API for the wider community it should be worthy of including as an additional function in System.Environment so that projects may rely on it. It's also a very simple standalone function which shouldn't knock-on in other areas and has minimal, if any, maintenance cost.

I want to add an environment variable check to PowerShell similar to the one in dotnet-cli that allows for runtime disabling of telemetry gathering without requiring the file-system to be modified, which would require duplicating the function in question.

Current method

var str = System.Environment.GetEnvironmentVariable("ENVIRONMENT_VAR_NAME");
var isTrue = false;
switch (str.ToLowerInvariant()) {
    case "true":
    case "yes":
    case "1":
        isTrue = true;
        break;
    case "false":
    case "no":
    case "0":
        isTrue = false;
        break;
    default:
        throw new System.ArgumentException("Environment variable was not truthy nor falsy", "ENVIRONMENT_VAR_NAME");
}

Proposed method

var isTrue = System.Environment.GetEnvironmentVariableAsBool("ENVIRONMENT_VAR_NAME");

Available implementations

The proposed function is currently implemented in dotnet-cli only.

Projects with similar marshalling

Searches

• GitHub Search - terms: "getEnvironmentVariable bool"
• Projects using NCrunch x26
• Projects detecting appveyor x73
• 47 results for exact function name - likely Microsoft projects and forks thereof

Individual projects

Dotnet CLI; Microsoft aspnet sdk; Microsoft Azure functions CLI; Microsoft Xamarin Forms; 1; 2; 3; 4; 5; 6; 7; 8

Proposed API

public static partial class Environment {
    // existing public members
    public static string GetEnvironmentVariable(string variable);
    public static string GetEnvironmentVariable(string variable, EnvironmentVariableTarget target);
    public static IDictionary GetEnvironmentVariables();
    public static IDictionary GetEnvironmentVariables(EnvironmentVariableTarget target);
    public static void SetEnvironmentVariable(string variable, string value);
    public static void SetEnvironmentVariable(string variable, string value, EnvironmentVariableTarget target);
    public static string CommandLine { get; }
    public static string CurrentDirectory { get; set; }
    public static int CurrentManagedThreadId();
    public static void Exit(int exitCode);
    public static void FailFast(string message);
    public static void FailFast(string message, Exception exception);
    public static string ExpandEnvironmentVariables(string name);
    public static string[] GetCommandLineArgs();
    public static string GetFolderPath(SpecialFolder folder);
    public static string GetFolderPath(SpecialFolder folder, SpecialFolderOption option);
    public static bool HasShutdownStarted();
    public static bool Is64BitProcess();
    public static bool Is64BitOperatingSystem();
    public static OperatingSystem OSVersion();
    public static int ProcessorCount();
    public static string StackTrace {
        [MethodImpl(MethodImplOptions.NoInlining)]
        get;
    }
    public static int TickCount();
    public static bool UserInteractive();
    public static Version Version { get; }
    public static long WorkingSet { get; }

    // new members
    public static bool GetEnvironmentVariableAsBool(string name, bool default = false);
}

Details

• The default parameter is for indicating the fallback value if the environment variable does not exist or does not contain a boolean-style value.

Open Questions

• Should the default parameter be omitted in favour of always returning false whenever the environment variable name does not contain a truthy value, or is undefined?
• Should the function throw an ArgumentException instead of providing a default value when the environment variable is undefined, or contains neither a truthy nor a falsy value such as foo and bar are neither truthy nor falsy values?

Updates

• Attempted to convert comment into more of a speclet style per the API review process document.

[danmosemsft]

@diddledan sounds good, can you please reformat with sections as suggested in https://github.com/dotnet/corefx/blob/master/Documentation/project-docs/api-review-process.md

That would organize the proposed API in C# format, suggestion of the implementation, rationale/why it's important enough and folks can't roll their own.

[danmosemsft]

BTW you mentioned adding to netstandard. .NET Standard 2.0 is shipped and fixed. Because .NET Standard defines a common subset of API's across various .NET platforms, for an API to get into a future .NET Standard version it must exist in those various platforms first. The first one to start with is CoreFX.

[karelz]

Note: We don't even have a method to parse environment value as an integer.

The proposal above adds parsing logic and several variants of possible true/false encodings into .NET Core. I don't think it is a good idea.
The values are not localized and it feels weird that we should decide in the platform how true/false can be encoded (it is not as straightforward as integer encoding and involves much more language-specific text/characters).

What might help IMO: Demonstrate there is non-trivial number of projects implementing such function on their own today. (e.g. search GitHub)

[danmosemsft]

I agree with @karelz : it feels odd to assume English.

[diddledan]

I've added some search results to the post indicating projects that I found from a quick browse of Github. The first 5 pages of the 100 pages of results from the first search (Terms: GetEnvironmentVariable bool; Filtered to only c# files) yeilded the second list of items and suggested the further searches:

Dotnet CLI; Microsoft aspnet sdk; Microsoft Azure functions CLI; Microsoft Xamarin Forms; 1; 2; 3; 4; 5; 6; 7; 8

[justinvp]

This might be a good candidate for a standalone helper API outside of corefx (corefxlab or 3rd party nuget package) that can be used to parse boolean strings (or better ReadOnlySpan<char>) in this way from any source (e.g. environment variables, command line args, windows registry, etc.).

[ericstj]

Closing this due to lack of recent interest + complexities with languages. As @justinvp mentioned this can be developed outside of dotnet/runtime.