Welcome

Author's notes...

Although many frameworks already exist for working with settings, most are complicated or over engineered for simple usage scenarios. I reluctantly created NSettings because I needed a library that satisfied these specific needs:

• The public API is simple and obvious.

• The dependencies and runtime footprint are as small as possible.

• Settings are identified by a key pair, also known as a compound key. The first part of the key is called the application key, the second part is called the item key. In combination they uniquely identify a setting. The application key can be used to partition possibly large numbers of settings into groups for easier management. The application key can be null which means the setting is not associated with any application name or group.

• The backing storage is customisable. The standard library include two implementations, one using an XML file as the backing storage, the other using the HKCU Registry hive as backing storage. The source code is available in the Azure DevOps Repository.

The original settings library with the XML file and Registry implementations was created back in the very early days of .NET, and is now probably redundant due to the decades of evolution of .NET, the app platforms and NuGet packages. However, this project remains published because it's used in some live products.

In 2025, a new project and package was added to the library to support storing settings in an Azure Table. Many modern apps require settings and similar values to be persisted in cloud storage, for improved security and reliability, and to allow distributed access. The API surface for the Azure settings library is as similar as possible to the legacy library. However, most methods in the new settings API are asynchronous because they make calls to asynchronous Azure Table APIs.

More comprehensive documentation and samples code is available on the NSettings Wiki Page.

The following skeleton code shows how an incrementing number can be persisted in settings using the legacy API.

int runCount;
:
var settings = new RegistrySettings();
runCount = settings.GetInt(null, nameof(runCount), 0);
++runCount;
:
Trace.WriteLine($"App run count is {runCount}");
:
settings.Put(null, nameof(runCount), runCount);

There are many simple and convenient methods to Put and Get commonly used types using the NSettings library. Nullable types and defaults are easy to handle.

long n1 = settings.GetLong(null, "MyNumber", long.MaxValue);  // A default value if not found
int? n2 = settings.GetInt(null, "YourNumber");                // Null if not found

Any properly implemented settings processor guarantees that the following types can be round-tripped as settings values.

• All FCL numeric types, signed, unsigned and Nullable<>.

• string and string[]

• byte[]

• Any type that has a two-way string TypeConverter. This includes most of the frequently used FCL classes such as Guid, DateTime, TimeSpan, etc. A user written class can be round-tripped if it has an associated string TypeConverter (a sample is provided in the unit test project).