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

All code examples expect the following using clauses:

usingIniParser;usingIniParser.Model;

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

//Create an instance of a ini file parservarparser=newIniDataParser();

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.varparser=newFileIniDataParser();

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

varparser=newFileIniDataParser();// This load the INI file, reads the data contained in the file, // and parses that dataIniDatadata=parser.ReadFile("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 sectionsforeach(SectionDatasectionindata.Sections){Console.WriteLine("["+section.Name+"]");//Iterate through all the keys in the current section//printing the valuesforeach(KeyDatakeyinsection.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"KeyDataCollectionkeyCol=data["GeneralConfiguration"];//This line gets the KeyData form the key "setUpdate"//defined in the section "GeneralConfiguration"stringdirectValue=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:

varparser=newFileIniDataParser();IniDatadata=parser.ReadFile("TestIniFile.ini");//Add a new section and some keysdata.Sections.AddSection("newSection");data["newSection"].AddKey("newKey1","value1");data["newSection"].AddKey("newKey2","value5");//Remove the last keydata["newSection"].RemoveKey("newKey2");//Remove the 'Users' section from the file and all keys and //comments associated to itdata.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:

varparser=newFileIniDataParser();//Get the dataIniDataparsedINIDataToBeSaved;//Save the fileparser.WriteFile("newINIfile.ini",parsedINIDataToBeSaved);

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

IniDatadata=newIniData();data["Section1"]["key1"]="value1";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