dotnet-config API

The main usage for .NET tool authors consuming the DotNetConfig API is to first build a configuration from a specific path (will assume current directory if omitted):

var config = Config.Build();

The resulting configuration will contain the hierarchical variables set in the current directory (or the given path), all its ancestor directories, plus global and system locations.

When getting values, the supported primitives are exposed as first-class methods for Add, Get and Set, so you get quite a few usability overloads for each of Boolean, DateTime, Number and String, such as AddBoolean, GetDateTime, GetString or SetNumber:

// reads from:
// [mytool]
//   enabled = true

bool? enabled = config.GetBoolean("mytool", "enabled");

// reads from:
// [mytool.editor]
//   path = code.exe

string? path = config.GetString("mytool.editor", "path");


// reads from:
// [mytool "src/file.txt"]
//   createdOn = 2020-08-23T12:00:00Z

DateTime? created = config.GetDateTime("mytool", "src/file.txt", "createdOn");
// If value was not found, set it to the current datetime
if (created == null)
    // Would create the section if it did not previously exist, and add the variable
    config.SetDateTime("mytool", "src/file.txt", "createdOn", DateTime.Now);

Alternatively you can use the TryGetXXX methods instead, to avoid checking for null return values in cases where the variable (in the requested section and optional subsection) is not found:

if (!config.TryGetDateTime("mytool", "src/file.txt", "createdOn", out created))
    config.SetDateTime("mytool", "src/file.txt", "createdOn", DateTime.Now);

Since .netconfig supports multi-valued variables, you can retrieve them all ConfigEntry and inspect or manipulate them granularly:

foreach (ConfigEntry entry in config.GetAll("proxy", "url"))
{
    // entry.Level allows inspecting the location where the entry was read from
    if (entry.Level == ConfigLevel.System)
        // entry came from Environment.SpecialFolder.System
    else if (entry.Level == ConfigLevel.Global)
        // entry came from Environment.SpecialFolder.UserProfile
    else
        // local entry from current dir .netconfig or an ancestor directory

    Console.WriteLine(entry.GetString());
    // entry.GetBoolean(), entry.GetDateTime(), entry.GetNumber()
}

When writing values (via AddXXX or SetXXX) you can optionally specify the configuration level to use for persisting the value, by passing a ConfigLevel:

// writes on the global .netconfig in the user's profile
//[vs "alias"]
//  comexp = run|community|exp

config.AddString("vs", "alias", "comexp", "run|community|exp", ConfigLevel.Global);