Laileb.IniFile 2.0.4

💾 IniFile

A lightweight .NET library for reading and writing Windows INI files via the native kernel32 API.

📋 Table of Contents

• 📖 About
• ✨ Features
• 🚀 Getting Started
  • 📌 Prerequisites
  • 📦 Installation
• 💡 Usage
• 📚 API Reference
• 🧪 Running Tests
• 🏗️ Project Structure
• 🤝 Contributing
• 📄 License

📖 About

IniFile is a thin, zero-dependency wrapper around the Windows kernel32.dll Private Profile functions (WritePrivateProfileString, GetPrivateProfileString, GetPrivateProfileInt, etc.).

It lets you read and write classic INI configuration files with a simple, strongly-typed C# API — no parsing logic needed.

⚠️ Note: This library uses Windows-only P/Invoke calls and is not cross-platform.

✨ Features

🚀 Getting Started

📌 Prerequisites

• OS: Windows 10 / 11 or Windows Server 2016+
• SDK: .NET 10 SDK or later
• Language: C# 14

📦 Installation

NuGet Package Manager

dotnet add package Laileb.IniFile

Or via the Package Manager Console in Visual Studio:

Install-Package Laileb.IniFile

Or add directly to your .csproj:

<PackageReference Include="Laileb.IniFile" Version="2.0.4" />

💡 Make sure to enable <AllowUnsafeBlocks>true</AllowUnsafeBlocks> in your .csproj (required by LibraryImport source generation).

💡 Usage

using Ini = IniFile.IniFile;

var ini = new Ini("config.ini");

// Write values
ini.Write("Host", "localhost", "Database");
ini.Write("Port", "5432", "Database");
ini.Write("Debug", "true", "Logging");

// Read values
string host = ini.ReadString("Host", "Database"); // "localhost"
int port = ini.ReadInt("Port", "Database"); // 5432
bool dbg  = ini.ReadBool("Debug", "Logging"); // true
string miss = ini.ReadString("Missing", "Nope", defaultValue: "N/A"); // "N/A"

// Enumerate
string[] sections = ini.GetAllSections(); // ["Database", "Logging"]
string[] entries  = ini.GetAllDataSection("Database"); // ["Host=localhost", "Port=5432"]

// Check & delete
bool exists = ini.KeyExists("Host", "Database"); // true
ini.DeleteKey("Host", "Database");
ini.DeleteSection("Logging");

👉 See the full working demo in examples/IniFile.Example/Program.cs.

📚 API Reference

🔨 Constructor

public IniFile(string filePath)

Creates a new instance bound to the given file path. The path is resolved to an absolute path internally. Throws ArgumentException if the path is null, empty, or whitespace.

🏷️ Properties

⚙️ Methods

✏️ Write

public bool Write(string key, string? value, string? section = null)

Writes a string value. Returns true on success. Creates the file, section, and key if they don't exist. When section is omitted or null, the wrapper uses an empty section name, which Windows serializes as [].

📖 ReadString

public string ReadString(string? key, string? section = null, string defaultValue = "", int bufferSize = 1024)

Returns the value for the key, or defaultValue if not found. When section is omitted or null, key reads use an empty section name, which Windows serializes as []. Passing null for key preserves the native enumeration behavior: key names for a section, or section names when both key and section are null.

🔢 ReadInt

public int ReadInt(string key, string? section = null, int defaultValue = -1)

Returns the integer value for the key, or defaultValue if the key is not found. Malformed numeric values follow the native GetPrivateProfileInt parsing behavior and may return 0 instead of defaultValue. When section is omitted or null, the wrapper uses an empty section name, which Windows serializes as [].

✅ ReadBool

public bool ReadBool(string key, string? section = null, bool defaultValue = false)

Returns true for "true", "1", "yes"; false for "false", "0", "no" (case-insensitive). Returns defaultValue for anything else. When section is omitted or null, the wrapper uses an empty section name, which Windows serializes as [].

📂 GetAllSections

public string[] GetAllSections(int bufferSize = 32768)

Returns an array of all section names. Returns an empty array if the file has no sections.

📋 GetAllDataSection

public string[] GetAllDataSection(string section, int bufferSize = 32768)

Returns an array of "key=value" strings for every entry in the given section.

🗑️ DeleteKey

public bool DeleteKey(string key, string? section = null)

Removes a key and its value. Returns true on success. When section is omitted or null, the wrapper uses an empty section name, which Windows serializes as [].

🧹 DeleteSection

public bool DeleteSection(string? section = null)

Removes an entire section. Returns true on success. When section is omitted or null, the wrapper deletes the empty [] section.

🔍 KeyExists

public bool KeyExists(string key, string? section = null)

Returns true if the key exists in the section (including keys with empty values). When section is omitted or null, the wrapper uses an empty section name, which Windows serializes as [].

🧪 Running Tests

dotnet test

Tests are located in tests/IniFile.Tests/ and use xUnit. They create temporary INI files in the system temp directory and clean up after each run.

🏗️ Project Structure

IniFile/
├── 📁 src/
│   └── 📁 IniFile/              # Library source
│       ├── 📄 IniFile.cs
│       └── 📄 IniFile.csproj
├── 📁 tests/
│   └── 📁 IniFile.Tests/        # xUnit tests
│       ├── 📄 IniFileTests.cs
│       └── 📄 IniFile.Tests.csproj
├── 📁 examples/
│   └── 📁 IniFile.Example/      # Console demo app
│       ├── 📄 Program.cs
│       └── 📄 IniFile.Example.csproj
├── 📄 Directory.Build.props      # Shared build settings
├── 📄 Directory.Packages.props   # Central package management
├── 📄 IniFile.slnx               # Solution file
└── 📄 README.md

🤝 Contributing

Contributions are welcome! To get started:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/my-feature)
3. ✏️ Make your changes and add tests
4. ✅ Run dotnet test to verify everything passes
5. 📬 Open a Pull Request

📄 License

This project is licensed under the MIT License.