First Steps

This page will show code examples that will help you use this parser for reading the contents of an INI file. See the configuring page to learn how to change the when parsing files.

INI File structure

An INI file const of various sections, each of one defines various unique keys with an unique value assigned to each key.

Sections are declared as a unique word enclosed in square brackets. Spaces enclosed into the square bracktes are ignored, but the section must be defined with an unique word( [ sampleSection ] )

Inside a section, we can define keys with a unique value. Keys must be unique within the same section, but can have the same key name in differents sections. A key is assigned using the equal sign (key = value)

In addition we can define single-line comments using a semicolon ( ; )

So, a simple INI file could be writen like this:

[ section ]
;comment
key = value

Details

The first thing to do is create an instance of a INI parser

//Create an instance of a ini file parser
var parser = new IniDataParser();

The ini parser can only work with INI data in a string, so if you want to parse a file or get the ini data, you can use some of the provided helper classes (FileIniParser or StreamIniParser), or just read the ini data source from whatever source as an string by yourself, and then use the IniDataParser.Parse method.

// Use a FileIniDataParser instance to easily parse or persist ini files.
var parser = new FileIniDataParser();

Now we can get the INI Data using the Method LoadFile from the parser object. This returns a new IniData instance which contains all the data parsed from the INI file:

// This load the INI file, reads the data contained in the fail, and parses that data
IniData parsedData = parser.LoadFile("TestIniFile.ini");

All Sections inside the ini file are represented by a SectionDataCollection, which is nothing more than a collection of SectionData instances. Each SectionData holds a string with the section's name, a list of strings holding the comments associated to that section, and a list of keys in the section. That list is represented by a KeyDataCollection, a collection of KeyData instances.

Accessing the data

The DataCollection types implements IEnumerator<T> so data can be iterated with a for each loop:

//Iterate through all the sections
foreach (SectionData section in data.Sections)
{
   Console.WriteLine("[" + section.Name + "]");
   
   //Iterate through all the keys in the current section
   //printing the values
   foreach(KeyData key in section.Keys)
      Console.WriteLine(key.Name + " = " + key.Value);
}

Direct access

We can access the data directly if we know the name of the section and key we need

//This line gets the SectionData from the section "GeneralConfiguration"
KeyDataCollection keyCol = data["GeneralConfiguration"];

//This line gets the KeyData form the key "setUpdate" defined in the section "GeneralConfiguration"
string directValue = keyCol["setUpdate"];

//But is easier to get the value in one shot:
directValue = data["GeneralConfiguration"]["setUpdate"];

The parsed data can also be easely mofified:

data["GeneralConfiguration"]["setUpdate"] = "150";

Adding or removing sections or keys

You can programaticaly add or remove either sections and/or key/value pairs:

//Make a copy of the parsed data
IniData newData = parser.ParsedData;

//Add a new section and some keys
newData.Sections.AddSection("newSection");
newData["newSection"].AddKey("newKey1", "value1");
newData["newSection"].AddKey("newKey2", "value5");

//Remove the last key
newData["newSection"].RemoveKey("newKey2");

//Remove the 'Users' section from the file and all keys and comments associated to it
newData.Sections.RemoveSection("Users");

Saving the file

Either if you make modifications to the parsed data, or if you create a new IniData instance and populate it, you probably want the data to be saved to a file. To do that, just use the 'SaveFile' method from the FileIniDataParser instance:

//Get the data
IniData parsedINIDataToBeSaved;
//Save the file
parser.SaveFile("newINIfile.ini", parsedINIDataToBeSaved);

You can also create a string with the contents of an INI file using the IniData.ToString() method.

// This string contains the ini data from the example file
string iniDataAlreadyReadElseWhere;
IniDataParser parser = new IniDataParser();

IniData data = parser.parse(iniDataAlreadyReadElseWhere);

Console.WriteLine(data.ToString());

---

Contents of the INI file used in the example

The INI file used in the example contains the following info:

;This section provides the general configuration of the application
[GeneralConfiguration] 

;Update rate in msecs
setUpdate = 100

;Maximum errors before quitting
setMaxErrors = 2

[UI]
fullscreen = false

;Users allowed to access the system
;format: user = pass
[Users]
ricky = rickypass
patty = pattypass