AbYzzX.Extensions.Settings.Ini 0.0.7.1

Abyzz.Extensions.Settings.Ini

INI file provider for the Abyzz.Extensions.Settings library. This package enables reading and writing configuration settings from standard INI files.

Overview

This package provides an ISettingsProvider implementation for INI file format, allowing you to use INI files as a configuration source in your .NET applications. It supports standard INI syntax with sections, key-value pairs, and comments.

Features

• Read and write standard INI files
• Section-based organization
• Comment support (lines starting with #)
• Optional and required file handling
• Automatic section creation during load
• Fluent API via extension methods
• Empty value support

Installation

dotnet add package AbYzzX.Extensions.Settings.Ini

This package automatically includes AbYzzX.Extensions.Settings as a dependency.

INI File Format

The provider supports standard INI file syntax:

# This is a comment
[Section1]
Key1=Value1
Key2=Value2

[Section2]
Host=localhost
Port=5432
Enabled=true

# Another comment
[Features]
MaxRetries=3
Timeout=30.0
EmptyValue=

Format Rules

• Sections: Defined by [SectionName]
• Key-Value Pairs: Written as Key=Value
• Comments: Lines starting with # are ignored
• Empty Lines: Blank lines are ignored
• Empty Values: Keys without values are stored as empty strings
• Whitespace: Leading and trailing whitespace is trimmed from keys and values

Usage

Basic Usage

using AbYzzX.Extensions.Settings;

var builder = new SettingsBuilder();
builder.AddProvider(new IniSettingsProvider("config.ini"));

var settings = builder.Build();

// Read values
var host = settings.GetString("Database", "Host");
var port = settings.GetInt32("Database", "Port", 5432);

Using Extension Method (Fluent API)

var settings = new SettingsBuilder()
    .AddIniFile("config.ini")
    .AddIniFile("optional.ini", isRequired: false)
    .Build();

Required vs Optional Files

By default, files are required and will throw an exception if not found:

// Throws FileNotFoundException if file doesn't exist
builder.AddIniFile("config.ini");
builder.AddProvider(new IniSettingsProvider("config.ini", isRequired: true));

For optional configuration files:

// No error if file doesn't exist
builder.AddIniFile("optional.ini", isRequired: false);
builder.AddProvider(new IniSettingsProvider("optional.ini", isRequired: false));

Reading Settings

var settings = new SettingsBuilder()
    .AddIniFile("config.ini")
    .Build();

// Get values with type conversion
var connectionString = settings.GetString("Database", "ConnectionString");
var timeout = settings.GetInt32("Database", "Timeout", 30);
var enableLogging = settings.GetBool("Features", "EnableLogging", false);

Working with Sections

// Get a specific section
var dbSection = settings.GetSection("Database");
if (dbSection != null)
{
    var host = dbSection.GetString("Host", "localhost");
    var port = dbSection.GetInt32("Port", 5432);
    var username = dbSection.GetString("Username");
}

// Check all available sections
foreach (var sectionName in settings.GetSectionNames())
{
    Console.WriteLine($"Section: {sectionName}");
}

Modifying and Saving Settings

var settings = new SettingsBuilder()
    .AddIniFile("config.ini")
    .Build();

// Modify existing values
var section = settings.GetSection("Database");
if (section != null)
{
    section.SetValue("Host", "newhost.example.com");
    section.SetValue("Port", "5433");
}

// Add new section and values
var newSection = settings.AddSection("NewFeature");
newSection.SetValue("Enabled", "true");
newSection.SetValue("MaxAttempts", "5");

// Save changes back to file
settings.Save();

The saved file will look like:

[Database]
Host=newhost.example.com
Port=5433

[NewFeature]
Enabled=true
MaxAttempts=5

API Reference

IniSettingsProvider

Constructor:

public IniSettingsProvider(string filePath, bool isRequired = true)

Parameters:

• filePath - Path to the INI file (relative or absolute)
• isRequired - Whether the file must exist (default: true)

Exceptions:

• FileNotFoundException - Thrown when the file doesn't exist and isRequired is true

Extension Methods

public static SettingsBuilder AddIniFile(
    this SettingsBuilder builder,
    string filePath,
    bool isRequired = true)

Adds an INI file provider to the settings builder using a fluent API.

Returns: The same SettingsBuilder instance for method chaining.

Example Configuration File

# Application Configuration
[Application]
Name=MyApplication
Version=1.0.0
Environment=Production

# Database Settings
[Database]
Host=localhost
Port=5432
Database=mydb
Username=admin
Password=secret
ConnectionTimeout=30

# Feature Flags
[Features]
EnableNewUI=true
EnableBetaFeatures=false
MaxConcurrentUsers=100

# Logging Configuration
[Logging]
Level=Information
LogToFile=true
LogPath=/var/log/myapp.log

Multiple INI Files

You can load multiple INI files, with later files overriding earlier ones:

var settings = new SettingsBuilder()
    .AddIniFile("appsettings.ini")
    .AddIniFile("appsettings.Development.ini", isRequired: false)
    .AddIniFile("appsettings.Local.ini", isRequired: false)
    .Build();

Error Handling

try
{
    var settings = new SettingsBuilder()
        .AddIniFile("config.ini")
        .Build();
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"Configuration file not found: {ex.FileName}");
    // Handle missing file
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"No settings providers added: {ex.Message}");
}

Best Practices

1. Use Optional Files for Environment-Specific Settings

   .AddIniFile("appsettings.ini")
   .AddIniFile($"appsettings.{env}.ini", isRequired: false)
   

2. Validate Critical Settings After Loading

   var settings = builder.Build();
   if (!settings.ContainsSection("Database"))
   {
       throw new InvalidOperationException("Database configuration missing");
   }
   

3. Use Type-Safe Extension Methods

   // Instead of manual parsing
   var port = settings.GetInt32("Server", "Port", 8080);
   // Not: int.Parse(settings.GetSetting("Server", "Port") ?? "8080")
   

4. Provide Sensible Defaults

   var timeout = settings.GetInt32("Connection", "Timeout", 30);
   var maxRetries = settings.GetInt32("Connection", "MaxRetries", 3);
   

Limitations

• Comments are not preserved when saving files
• No support for multi-line values
• No support for quoted values containing = characters
• Section and key names are case-insensitive
• Keys without a section are not supported

Requirements

• .NET 10.0 or later

Related Packages

• AbYzzX.Extensions.Settings - Core implementation (automatically included)
• AbYzzX.Extensions.Settings.Abstractions - Core interfaces

Contributing

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