VeselovAndrey/SolidCode.Extensions.Configuration.Yaml

YAML configuration support for Microsoft.Extensions.Configuration.

SolidCode.Extensions.Configuration.Yaml

SolidCode.Extensions.Configuration.Yaml is a library that provides YAML configuration support for Microsoft.Extensions.Configuration.

YAML is often used for configuration files due to its human-readable format. But often not all its features are required for describing configuration settings. For example: tags, including JSON inside YAML, document stream, etc.

This library aims to achieve performance and low memory consumption by supporting YAMLite - a subset of YAML features most used in configuration files.

Currently supported features:

• Mappings
• Sequences
• Scalars (including multi-line strings)
• Comments

Considering to be supported in the future:

• Flow style for sequences

Not supported features:

• Tags
• Anchors
• Aliases
• Document stream
• Full flow style support (e.g. JSON inside YAML)

Installation

You can install the SolidCode.Extensions.Configuration.Yaml library using the following command:

dotnet add package SolidCode.Extensions.Configuration.Yaml 

Or via NuGet Package Manager in Visual Studio:

PM> Install-Package SolidCode.Extensions.Configuration.Yaml

Usage

To use the SolidCode.Extensions.Configuration.Yaml library, follow these steps:

1. After installation, the library will be referenced in your project.

2. Create a YAML configuration file in your project, for example appsettings.yaml, and define your configuration settings in YAML format.

3. In your code, call the AddYamlFile() method to add a YAML configuration file into the application configuration alongside with other configuration sources. For example:

IHostBuilder appBuilder = Host.CreateDefaultBuilder()
	.ConfigureAppConfiguration((hostingContext, config) => {
		config.AddYamlFile("appsettings.yaml", reloadOnChange: true, configurationOptions: options);
	});

IHost host = appBuilder.Build();

4. Access your configuration settings using the IConfiguration interface and/or options patterns as usual.

Documentation

AddYamlFile() method

To add a configuration file to your application configuration, please use the AddYamlFile() method:

AddYamlFile(this IConfigurationBuilder builder, string path, bool optional = false, bool reloadOnChange = true, YamlConfigurationOptions? configurationOptions = null)

Parameters:

• path - the path to the YAML configuration file. The path can be relative to the application root directory or an absolute path.
• optional - whether the file is optional.
• reloadOnChange - whether the configuration should be reloaded if the YAML file changes.
• configurationOptions - allows to specify options for parsing the YAML configuration file. Options represented by the YamlConfigurationOptions class described below.

YamlConfigurationOptions class

This class has following properties:

• BufferSize - specifies the size of the buffer (in characters) used to read the YAML file. The default value is equal to the configuration file size.
• EndOfLineType - specifies the type of end-of-line character(s) used in the configuration values. The default value is the default end-of-line character(s) for the current operating system.
• EndingLineBreaks - defines how to handle the final line break in the multiline string. Options are:
  • keep as is
  • remove any ending line breaks
  • normalize (default value): keep only 1 line break regardless of how many line breaks were in the YAML file.

Exceptions

• YamlConfigurationException - the base exception for all exceptions thrown by the library.
  • YamlConfigurationReadingException - thrown if there is an error while reading the YAML configuration.
  • YamlConfigurationParsingException - thrown if there is an error while parsing the YAML configuration.

Benchmarks

Here is example of benchmark results for parsing YAML files (see SolidCode.Extensions.Configuration.Yaml.Benchmark project source code for YAML files):

BenchmarkDotNet v0.14.0, Windows 11 (10.0.22631.3958/23H2/2023Update/SunValley3)
11th Gen Intel Core i9-11900H 2.50GHz, 1 CPU, 16 logical and 8 physical cores

| Method                                              | Mean      | Error     | StdDev    | Ratio | Gen0    | Gen1    | Allocated | Alloc Ratio |
|---------------------------------------------------- |----------:|----------:|----------:|------:|--------:|--------:|----------:|------------:|
| 'YamlConfigurationParser. File: example_large.yaml' |  33.88 us | 0.250 us  | 0.208 us  |  0.07 |  5.7983 |  0.8545 |  71.32 KB |        0.16 |
| 'YamlDotNet-based parser. File: example_large.yaml' | 456.30 us | 5.036 us  | 4.711 us  |  1.00 | 35.6445 | 12.6953 | 442.05 KB |        1.00 |

| Method                                              | Mean      | Error     | StdDev    | Ratio | Gen0    | Gen1    | Allocated | Alloc Ratio |
|---------------------------------------------------- |----------:|----------:|----------:|------:|--------:|--------:|----------:|------------:|
| 'YamlConfigurationParser. File: example_small.yaml' |  7.607 us | 0.0558 us | 0.0494 us |  0.10 | 1.0834  | 0.0305  |   13.3 KB |        0.19 |
| 'YamlDotNet-based parser. File: example_small.yaml' | 73.380 us | 0.6213 us | 0.5508 us |  1.00 | 5.7373  | 0.6104  |  70.79 KB |        1.00 |

YamlDotNet library version: 16.3.0

License

This library is licensed under the MIT License.