Net4x.Configuration.Library 2.5.0.26287

Net4x.Configuration.Library

A library for reading and writing application settings. It gives one key/value view over several sources: XML .config files, JSON files, URI query strings, environment variables and Microsoft.Extensions.Configuration. It targets .NET Framework 3.5 and later as well as .NET Standard 2.0.

Installation

dotnet add package Net4x.Configuration.Library

Target frameworks: net35, net40, net45, net461, netstandard2.0.

Reading settings with ArgumentGetter

ArgumentGetter.Instance is a process-wide entry point. By default it reads from the entry assembly's configuration.

using ConfigurationLibrary.Arguments;

var culture   = ArgumentGetter.Instance["Culture"];                      // string, "" when missing
int? retries  = ArgumentGetter.Instance.IntegerFromArguments["Retries"];
bool? verbose = ArgumentGetter.Instance.BooleanFromArguments["Verbose"];

Settings in environment variables are merged into the same dictionary, so ArgumentGetter.Instance["USERNAME"] works without extra setup.

Choosing the source

using ConfigurationLibrary.Configuration;

// Read <assembly>.json instead of <assembly>.config
ArgumentGetter.Instance.BaseConfigType = typeof(IJsonConfig);

// Point at another file (resolved as <Location>.config / <Location>.json)
ArgumentGetter.Instance.Location = "AppSeparated";

JSON layout:

{
  "appSettings": {
    "One": "1",
    "Plugin": "exe|My.Namespace.Processor|My.Assembly"
  }
}

Reading from a stream

ArgumentGetter.Instance.BaseConfig.Stream = myStream;
try
{
    var value = ArgumentGetter.Instance["One"];
}
finally
{
    // The configuration is process-wide, so detach the stream when you are done.
    ArgumentGetter.Instance.BaseConfig.Stream = null;
}

Typed values from Microsoft.Extensions.Configuration

var configuration = new ConfigurationBuilder().AddJsonFile("config.json").Build();

ArgumentGetter.Instance.Configuration = configuration;
var folders = ArgumentGetter.Instance
    .GetFromArgument<Dictionary<string, string>>("Data:TargetFolderLocations");

// or use a getter typed for the target
var typed = ArgumentGetter<Dictionary<string, string>>.Instance;
typed.Configuration = configuration;
var sameFolders = typed.FromArguments["Data:TargetFolderLocations"];

Working with a configuration directly

AppConfig, JsonConfig and UriConfig expose shared instances through Instance, and standalone ones through CreateNewInstance():

using ConfigurationLibrary.Configuration.Xml;

var config = AppConfig.Instance;
config.Location = typeof(Program).Assembly.Location;

int? port = config.GetIntegerValue("Port");
DateTime? since = config.GetDateValue("Since", "yyyy-MM-dd");
config["LastRun"] = DateTime.Now.ToString("O");
config.Save();

using ConfigurationLibrary.Configuration.Uri;

UriConfig.Instance.CurrentUri = new Uri("http://localhost?One=1&Plugins=a|b|c");

Where Save() writes

Save() does not overwrite the file shipped with the application. It writes a per-user copy to %USERPROFILE%\<AssemblyCompany>\<file name>.config (or .json). When the entry assembly has no AssemblyCompany attribute, its name is used instead. On the next load, that copy is merged over the shipped file.

AllSettings environment variable

Several settings can be passed in one environment variable called AllSettings, as key=value pairs joined by ArgumentGetter.Instance.Separator:

AllSettingsHelper.PutAllSettingsInArgumentGetter();

Other utilities

• StringsHelper.Instance: FirstNonEmptyString, MakeCamelPascalCase
• HttpUtility: URL decoding that also works on .NET Framework 3.5/4.0
• "...".TryParseJson<T>(out var result): JSON parsing that returns false instead of throwing
• AppConfigFactory.Instance: the factory behind every shared configuration instance
• AppConfigFactoryVariables.Instance.DefaultIsCaseSensitive: key case sensitivity (default true)

Related packages

• Net4x.Configuration.Interfaces: the contracts this library implements
• Net4x.Configuration.Crypt: encrypts and decrypts configuration values

Copyright (c) Piero Viano. All rights reserved. Authors: Piero Viano