Search Results for

    Show / Hide Table of Contents

    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);
    
    • Improve this Doc
    In This Article
    Back to top Generated by DocFX