AbYzzX.Extensions.Settings.Abstractions 0.0.7.1

Abyzz.Extensions.Settings.Abstractions

Core abstractions and interfaces for the Abyzz.Extensions.Settings library. This package provides the foundational contracts for building custom settings providers and working with configuration data.

Overview

This package contains the core interfaces and extension methods that define the settings management API. It's designed to be implementation-agnostic, allowing developers to create custom providers for any configuration source while maintaining a consistent API.

Purpose

Use this package when you want to:

• Create custom settings providers for specific configuration sources
• Reference the settings interfaces without pulling in the full implementation
• Build libraries that work with settings without depending on concrete implementations
• Maintain loose coupling in your architecture

Installation

dotnet add package AbYzzX.Extensions.Settings.Abstractions

Core Interfaces

ISettings

The main interface for managing configuration settings across multiple sections.

public interface ISettings
{
    string? GetSetting(string sectionName, string key);
    ISettingsSection AddSection(string sectionName);
    ISettingsSection? GetSection(string sectionName);
    bool ContainsSection(string sectionName);
    IReadOnlyCollection<string> GetSectionNames();

    void Load();
    void Save();
}

Methods:

• GetSetting(sectionName, key) - Retrieves a setting value from a specific section
• AddSection(sectionName) - Creates or retrieves a section
• GetSection(sectionName) - Gets an existing section or null
• ContainsSection(sectionName) - Checks if a section exists
• GetSectionNames() - Returns all section names
• Load() - Loads settings from all registered providers
• Save() - Saves settings to all registered providers

ISettingsSection

Represents a section containing key-value pairs.

public interface ISettingsSection
{
string SectionName { get; }

    void Add(string key, string value);
    void Remove(string key);
    bool ContainsKey(string key);
    
    IEnumerable<string> GetKeys();
    
    string? GetValue(string key);
    void SetValue(string key, string value);
}

Properties:

• SectionName - The name of the section

Methods:

• Add(key, value) - Adds a key-value pair
• Remove(key) - Removes a key
• ContainsKey(key) - Checks if a key exists
• GetKeys() - Returns all keys in the section
• GetValue(key) - Retrieves a value or null
• SetValue(key, value) - Sets or updates a value

ISettingsProvider

Interface for implementing custom configuration providers.

public interface ISettingsProvider
{
    void Load(ISettings settings);
    void Save(ISettings settings);
}

Methods:

• Load(settings) - Load configuration data into the settings object
• Save(settings) - Persist settings data to the underlying storage

Extension Methods

The package includes extension methods for type-safe value retrieval with default values.

For ISettings

var stringValue = settings.GetString("Section", "Key", "default");
var intValue = settings.GetInt32("Section", "Port", 8080);
var boolValue = settings.GetBool("Section", "Enabled", false);
var doubleValue = settings.GetDouble("Section", "Timeout", 30.0);
var decimalValue = settings.GetDecimal("Section", "Price", 0m);
var dateValue = settings.GetDateTime("Section", "Date", DateTime.Now);
var enumValue = settings.GetEnum<MyEnum>("Section", "Status", MyEnum.Default);

For ISettingsSection

var section = settings.GetSection("Database");
if (section != null)
{
    var host = section.GetString("Host", "localhost");
    var port = section.GetInt32("Port", 5432);
    var enabled = section.GetBool("Enabled", true);
}

Supported Types

• GetString() - String values
• GetInt16() - Short integers
• GetInt32() - Integers
• GetInt64() - Long integers
• GetBool() - Boolean values
• GetDouble() - Double precision numbers
• GetDecimal() - Decimal numbers
• GetDateTime() - Date and time values
• GetEnum<T>() - Enumeration values

All extension methods support optional default values that are returned when the key doesn't exist or parsing fails.

Boolean Value Handling

Boolean values are evaluated based on a configurable list of "true" values. By default, these are considered true (case-insensitive):

• "true"
• "1"
• "yes"

You can customize this behavior:

SettingsExtensions.BoolTrueValues = new[] { "true", "1", "yes", "on", "enabled" };

Creating Custom Providers

Implement the ISettingsProvider interface to create a provider for your configuration source:

public class JsonSettingsProvider : ISettingsProvider
{
private readonly string _filePath;

    public JsonSettingsProvider(string filePath)
    {
        _filePath = filePath;
    }

    public void Load(ISettings settings)
    {
        // Read JSON file
        // Parse structure
        // Populate settings using AddSection() and SetValue()
        
        var section = settings.AddSection("MySection");
        section.SetValue("Key", "Value");
    }

    public void Save(ISettings settings)
    {
        // Iterate through settings.GetSectionNames()
        // Build JSON structure
        // Write to file
        
        foreach (var sectionName in settings.GetSectionNames())
        {
            var section = settings.GetSection(sectionName);
            // Process section data
        }
    }
}

Use Cases

Library Development

When building a library that needs configuration but shouldn't dictate the configuration source:

public class MyLibrary
{
    public MyLibrary(ISettings settings)
    {
        var timeout = settings.GetInt32("MyLibrary", "Timeout", 30);
        // Use settings without knowing the source
    }
}

Multiple Provider Support

Create applications that combine multiple configuration sources:

// Hypothetical usage
builder.AddProvider(new JsonSettingsProvider("appsettings.json"));
builder.AddProvider(new EnvironmentSettingsProvider());
builder.AddProvider(new DatabaseSettingsProvider(connectionString));

Testing

Mock the interfaces for unit testing:

var mockSettings = new Mock<ISettings>();
mockSettings
.Setup(s => s.GetSetting("Section", "Key"))
.Returns("TestValue");

Requirements

• .NET 10.0 or later
• C# 14.0 or later (for extension member syntax)

Related Packages

• AbYzzX.Extensions.Settings - Default implementation of the abstractions
• AbYzzX.Extensions.Settings.Ini - INI file provider implementation

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.