NeoIni 3.2.2

📖 Documentation & Wiki — detailed guides, API reference, and examples

NeoIni

Secure, thread-safe INI configuration library for .NET with built-in integrity checking, AES-256 encryption, and a pluggable provider architecture.

dotnet add package NeoIni

• Package: nuget.org/packages/NeoIni
• Version: 3.2.2 | .NET 6+ | .NET Standard 2.0
• Developer: Lonewolf239

Features

Quick Start

Creating an instance

using NeoIni;

// Plain
NeoIniDocument document = new("config.ini");

// Auto-encryption (machine-bound)
NeoIniDocument encrypted = new("config.ini", EncryptionType.Auto);

// Custom password (portable between machines)
NeoIniDocument portable = new("config.ini", "MySecretPass123");

// Async
NeoIniDocument document = await NeoIniDocument.CreateAsync("config.ini", cancellationToken: ct);

Reading & writing values

// Write
document.SetValue("Database", "Host", "localhost");
document.SetValue("Database", "Port", 5432);

// Read with typed defaults
string host = document.GetValue("Database", "Host", "127.0.0.1");
int    port = document.GetValue("Database", "Port", 3306);

// Read without side effects (no AutoAdd, no file modification)
int level = document.TryGetValue("Game", "Level", 1);

// Async
await document.SetValueAsync("Database", "Host", "localhost");
string host = await document.GetValueAsync("Database", "Host", "127.0.0.1", ct);

• Missing sections/keys return defaultValue; with UseAutoAdd enabled the key is created automatically.
• Supports enum, DateTime, and any IConvertible type via invariant-culture parsing.

Section & key management

document.AddSection("Cache");
document.RemoveKey("Cache", "OldKey");
document.RenameSection("Cache", "AppCache");

string[] sections = document.GetAllSections();
string[] keys     = document.GetAllKeys("AppCache");
bool exists       = document.SectionExists("AppCache");

Search

var results = document.Search("token");
foreach (var r in results)
    Console.WriteLine($"[{r.Section}] {r.Key} = {r.Value}");

File operations

document.SaveFile();
document.Reload();
document.DeleteFile();
document.DeleteFileWithData();

Options & presets

document.UseAutoSave = true;
document.AutoSaveInterval = 3;    // save every 3 writes
document.UseAutoBackup = true;
document.UseAutoAdd = true;
document.UseChecksum = true;
document.SaveOnDispose = true;
document.AllowEmptyValues = true;

Or use built-in presets: NeoIniOptions.Default, Safe, Performance, ReadOnly, BufferedAutoSave(n).

Events

document.Saved            += (_, _) => Console.WriteLine("Saved");
document.Loaded           += (_, _) => Console.WriteLine("Loaded");
document.KeyChanged       += (_, e) => Console.WriteLine($"[{e.Section}] {e.Key} → {e.Value}");
document.KeyAdded         += (_, e) => Console.WriteLine($"[{e.Section}] +{e.Key}");
document.ChecksumMismatch += (_, _) => Console.WriteLine("Checksum mismatch!");
document.Error            += (_, e) => Console.WriteLine($"Error: {e.Exception.Message}");

Encryption & migration

// Auto-encryption — key is derived from user/machine/domain + per-file salt
NeoIniDocument document = new("secure.ini", EncryptionType.Auto);

// Retrieve password to migrate to another machine
string password = document.GetEncryptionPassword();

// On the new machine
NeoIniDocument migrated = new("secure.ini", password);

Disposal

using NeoIniDocument document = new("config.ini");
// SaveFile() is called automatically if SaveOnDispose is true
// After disposal — ObjectDisposedException on any access

Advanced Features

• Attribute-based mapping & source generator (1.7+) — detailed guide
• Hot-reload (1.7.1+) — usage & caveats
• Human-editable INI mode (1.7.2+) — experimental mode
• Pluggable provider abstraction (1.7.3+) — custom providers
• Pluggable encryption (2.0+) — custom encryption providers

API Reference

Full method, options, and event reference — API.md

Philosophy

Black Box Design — all internal logic is hidden behind the simple public API of NeoIniDocument. You work only with methods and events, without thinking about implementation details. NeoIni config files are owned and managed by the library; human comments are intentionally not preserved in standard mode (the in-file warning header signals this). For hand-edited configs, use Human-editable mode.