polarbeardk / miracle.settings

Load your application settings into strong typed objects with two lines of code.

Miracle.Settings

Load application settings into strong typed objects with two lines of code.

• No need to write code that load, convert and validate each configuration value.
• No "magic strings" and no defaults scattered around in source files.
• Loaded models are guaranteed to be valid.
• Get detailed error message on load error, describing exactly which setting has failed.
• Load settings at startup and application fails immediately upon bad configuration (Fail fast).
• Load complex structores like nested objects, arrays, lists and dictionaries.
• Use DI to inject strong typed setting models into application at startup.
• Works with Full .NET and .NET Core.

Table of content

• Miracle.Settings
  • Table of content
  • Install
  • Usage
  • Nested objects
  • Arrays, Lists & Dictionaries
• Advanced topics

Install

Available as a NuGet package: Miracle.Settings

To install Miracle.Settings, run the following command in the Package Manager Console

PM> Install-Package Miracle.Settings

Usage

A basic example on how to load settings into a POCO object.

<configuration>
  <appSettings>
    <add key="Foo" value="Foo string" />
    <add key="Bar" value="42" />
  </appSettings>
</configuration>

// Setting model that appSettings are loaded into
public class FooBar
{
    public string Foo { get; private set; }
    public int Bar { get; private set; }
}

The POCO (Plain Old CLR Object) that settings are serialized/loaded into.

ISettingsLoader settingsLoader = new SettingsLoader();
// Get settings at "root" level (without a prefix)
var settings = settingsLoader.Create<FooBar>();

This code loads settings of type of type FooBar into settings variable.

Top Tip! Load settings ONCE at startup, and expose settings to application using Dependency Injection.

Nested objects

Nested objects are supported using property separator (configurable using: SettingLoader.PropertySeparator)

<configuration>
  <appSettings>
    <add key="MyPrefix:Foo" value="Foo string" />
    <add key="MyPrefix:Nested:Foo" value="Foo" />
    <add key="MyPrefix:Nested:Bar" value="42" />
  </appSettings>
</configuration>

public class FooBar
{
    public string Foo { get; private set; }
    public Nested Nested { get; private set; }
}

public class Nested
{
    public string Foo { get; private set; }
    public int Bar { get; private set; }
}

// Get settings prefixed by "MyPrefix"
var settings = settingsLoader.Create<FooBar>("MyPrefix");

Arrays, Lists & Dictionaries

Collections (Arrays, Lists & Dictionaries) can be loaded implicitly into setting model properties, or explicitly by calling CreateArray/CreateList/CreateDictionary .

Simple arrays and lists can be loaded from a single string value containing separated values. See Controlling settings with annotations

More advanced scenarios requires a separate value for each collection item. Keys must be unique, so collection keys must be suffixed by something to make them unique.

<configuration>
  <appSettings>
    <add key="MyPrefix.1" value="Foo string" />
    <add key="MyPrefix.2" value="Foo" />
    <add key="MyPrefix.x" value="42" />
  </appSettings>
</configuration>

// Get the same settings as array, list & dictionary.

// With array and list, the "key" path is lost.
string[] settings1 = settingsLoader.CreateArray<string>("MyPrefix");
List<string> settings2 = settingsLoader.CreateList<string>("MyPrefix");

// With dictionary, the part of the key after prefix is used as dictionary key.
// In this case this would produce keys: "1","2","x"
Dictionary<string,string> settings3 = settingsLoader.CreateDictionary<string>("MyPrefix");

Elements in Arrays and Lists are returned in the same order as they are returned by the value provider. The AppSettings value proveider returns values in the same order as they are specified.

Advanced topics

• Controlling settings with annotations
• Type converters
• Value providers
• Validating settings

miracle.settings's Issues

Nullable<MyEnum> fails to load the value

Related to #2 . See the initial investigation done there.

All target frameworks are impacted.

Here is the line I stepped into:

.IsEnum is evaluated to false for nullable enums.

Can I load settings from a dictonary?

Hi I would like to load setting from a database, are there a way to load data from a dictionary or list of objects.
I would like to take advantages of the type safe loading you have build

Simple nullables (int? MyEnum?) throws in .NET Core when settingKey: null

Repro changeset in: #1

.NET Core only, because of this piece: ConfigurationValueProvider.cs

public bool TryGetValue(string key, out string value)
		{
			value = _configurationRoot[key];
			return value != null;
		}

For settingKey: null in JSON config _configurationRoot[key]; returns ""

It works in .NET Framework:

If I change the setting entry to: settingKey: "" it throws the same error.