Woof.Config 6.2.0-alpha.2

Woof.Config

.NET extension created by CodeDog

Distributed under MIT License. (c)2021 by CodeDog, All rights reserved.

About

A proper solution to replace the legacy .NET project XML settings. Universal application settings in JSON for both Linux and Windows programs.

A modern solution using the cutting edge .NET 6.0 JsonNode tech.

History

JsonNode

If you haven't heard about JsonNode in 2021, that's expected. When .NET 6.0 was officialy released that class is completely not advertised or mentioned among .NET 6.0 features. Tech blogs describe it as being experimental, though the mentions I've found was from the time from before official release.

From the other hand you probably couldn't code in C# not knowing the great Netwtonsoft.Json: the most popular NuGet package!

Even Microsoft was using it in early versions of .NET as dependency for Core projects, it was used for JSON IConfigurationProvider.

Then it was replaced with their own solution: System.Text.Json, more specifically: System.Text.Json.JsonDocument and System.Text.Json.JsonElement classes.

However until .NET 6.0 - it was read only. You could read JSON files and parse them as document trees, but creating and modifying such trees was not possible then.

And here we have JsonNode, the proper .NET replacement for Newtonsof.Json. It has everything, it's blazing fast, it's built in and it's super easy to use in modern C# code.

Woof.Config module is based on JsonNode. It's aimed to provide DI free, super easy to implement application configuration for all kind of cross-platform .NET projects.

It connects the powerful Microsoft's IConfiguration interface with JsonNode. Directly. Each IConfigurationSection is bound directly to its corresponding JsonNode object.

That gives the configuration mutability by default. You change a configuration value, the associated JSON document is changed and the changes can be saved.

Mutable JSON configurations

For now - to make it possible - the original value must not be nullable. It stems from how the configuration binder works.

Each value in IConfiguration can be either IConfigurationSection and in fact, internally, is a IConfiguration section, just one that actually has a string value.

Even in JSON - values have types. The JSON structure defines the types of values as being either text, number, bolean value, object or array.

The type is obvious from the syntax except one case - the null value.

It doesn't provide any type information and that's exact reason why nullable configuration values cannot be used in fully mutable configurations.

Usage

The goal is to provide a dynamic configuration for the C# program that is easily accessible and editable either by the user or the app itself.

The location of the file must be obvious. So does it's name.

The name of the file without extension matches the main program executable name.

The file can reside either in user's directory, or in the same directory the application is installed.

It's a similar idea to the legacy .NET project XML configuration files.

The Woof.Config module determines the location of the file internally. It searches for it first in the main executable directory, then in user's directory.

Linux path:

(In search order)

• ./[executable_name].json
• ~/.[executable_name]/[executable_name].json

Windows path:

• .\[executable_name].json
• %LOCALAPPDATA%\[company]\[product]\[executable_name].json
• %LOCALAPPDATA%\[product]\[executable_name].json
• %LOCALAPPDATA%\[executable_name]\[executable_name].json

In development, the configuration should just be copied to the output directory, then it can be moved to user's directory either by the application or the application installer.

Once Woof.JsonConfig object is loaded, it provides both pahts for that purpose.

In order to use the configuration the JSON file must be created first.

It provides the structure for the configuration properties.

Then, to access the configuration data in program - either IConfiguration methods and properties can be used, or the object can be bound to a strong typed configuration record with IConfiguration.Get<T>() extension.

Yes, the recommended type for the configuration section is a record type. All objects (mapped to sections) should be read-only pre-initialized getters.

Each complex type must be defined as section record.

For example, if we defined the configuration both in JSON file and already created a strong typed record for it named Configuration, here's an example usage:

var jsonConfig = new JsonConfig();
var config = jsonConfig.Get<Configuration>();

In order to modify a configuration value use IConfiguration.SetValue<T>() extension method.

A modified configuration can be saved like this:

await jsonConfig.SaveAsync();

or

jsonConfig.Save();

For more details see the provided examples and use built-in XML documentation.

Version 6.2 API change

This package is incompatible with older versions. Previous Woof.Config packed too many features in one module. It provided both data protection, Azure Key Vault access and data encryption.

Those features was moved to separate packages:

• Woof.Config.AKV
• Woof.Config.Protected
• Woof.Config.AKV.Protected

In order to use multi platform compatible data protection the .Protected packages depend on Woof.LinuxAdmin - that can configure the data protection for Linux system automatically.

Read the packages documentation in order to migrate.

Compatibility

The package is compatible with .NET 6.0 or newer. The applications using the module can run both on Windows and Linux.

This package was thoroughly tested on Windows 11 and Ubuntu 20.

Disclaimer

Please report any issues on GitHub.

Woof Toolkit is a work in progress in constant development, however it's carefully maintained with production code quality.

Pre-release packages are not fully tested. Use them with caution. Not all features will work as described, or at all. They sole purpose is to test the package before the official release.

You can use pre-release packages safely when you test all used features properly by yourself. Please don't forget to report issues on GitHub! It helps with the package development and improves the quality.