Click here to Skip to main content
13,835,559 members
Click here to Skip to main content
Add your own
alternative version


78 bookmarked
Posted 20 Aug 2007
Licenced CPOL

INI Files

, 2 Jul 2008
Rate this:
Please Sign up or sign in to vote.
Parse, manage, edit and write INI files while preserving their format. And don't get too exhausted.
; for 16-bit app support
[mci extensions]
[MCI Extensions.BAK]

(My win.ini)


It is strange to write a parser of INI files each time it is needed. Why not use an existing one, especially if it is good? I give you a class library that has the following features:

  • Parses INI files using given format directions.
  • Edits them easily using one single class.
  • Automatically finds out a formatting convention.
  • Adds commentaries to the sections and values just by setting a property Comment.
  • Writes a file to the disc, preserving its original format.
  • Enjoys richly documented code.


INI [=initialization] files are used to store settings that define the start-up state of some programs. Alternatively, they can just contain configuration data. Currently they can be found in special folders (desktop.ini) like "My Documents." A lot of them exist in the Windows root folder, e.g. C:\Windows\win.ini. In this article, I will use the following terminology:

[Abcd]  <- "Section"
Number=188  <- "Key" (vel "Value name") and "Value"

Using the Code

I will present three main usage guides of my library: User-Mode, Hardcore-Mode and Light-Mode.


The IniFile namespace contains one class: IniFile. It represents an object model of an INI file, which stores a whole structure in memory. Usage of IniFile is extremely simple.

IniFile file = new IniFile();
// Adds a new section with one value

file["LastUser"]["Name"] = "Gajatko";
// Save to disc


This will give the following output:


The indexer of IniFile returns an object that also has an indexer. However, it also has many other features. For example, it has a Comment property:

file["LastUser"].Comment =
@"This section contains information about user
which logged in at previous program run";
file["LastUser"].SetComment("Name", "Name of user");


;This section contains information about user
;which has logged in at previous program run
;Name of user

We can freely manipulate values and sections:

// Rename sections and keys

file["LastUser"].Name = "RecentUser";
file["RecentUser"].RenameKey("Name", "Login");
// Get names of all section:

string[] sections = file.GetSectionNames();
// Set existing values:

file["RecentUser"]["Login"] = "Chuck";
// Override existing comment:

file["RecentUser"].Comment = "New Comment";


;New Comment
;Name of user

Also, inline comments are supported:

file["RecentUser"].InlineComment = "An inline thing";


[RecentUser]   ;An inline thing

We can save all changes to a file and read from it, as well:

file = IniFile.FromFile("test.txt");

More methods and properties will appear in the auto-completion service in Visual Studio. They are all commented using Summary blocks. Files edited with the IniFile class will preserve their formatting.

Concluding: the User-Mode is cool, isn't it?



Actually, this library contains 10 classes. The first two are implementations of StreamReader and StreamWriter:

  • IniFileReader - Reads and parses a text file.
  • IniFileWriter - Writes INI file elements to a disc.

The second group of classes is used by User-Mode:

  • IniFile - Contains the whole INI file in memory and enables easy access to it.
  • IniFileSection - Represents a section and its values.

An INI file's Elements are the core objects of the IniFiles namespace. Usually they represent single lines of a file, but sometimes more.

  • IniFileSectionStart - Represents a beginning line of a section, like "[LastUser]".
  • IniFileValue - Represents a single line with a value, like "Name=Gajatko".
  • IniFileBlankLine - Represents one or more blank lines. The actual number of them is specified in the Amount property.
  • IniFileComment - Represents one or more commentary lines.

The class IniFileElement is a base class for them all. It has standard properties that are used by Reader and Writer:

  • Line - An actual representation of the object in the INI file. The name is a little confusing because sometimes the Line contains more than one line.
  • Content - Similar to Line, but without indentation.
  • Indentation - A string of all white spaces (tabs, spaces) preceding a meaningful content.
  • Formatting - A formatting string specific to a particular type of INI file element.

IniFileSettigs is a static class that contains all format settings used by other parts of the library. Sample settings are:

  • PreserveFormatting - Default true. If set to false, the Format() method will be called for all INI file elements while writing a file. The demo shows how it works.
  • CommentChars - Array of strings that begin a comment line, by default { ";", "#" }. When adding new comments, the first string in the array is used.
  • GroupElements - As said before, when the parser runs into a multiline commentary or blank lines, it will group them into one object. Setting this property to false will prevent this practice.
  • QuoteChar - A nullable char. Default value is null, but can be set to e.g. " (double qoutation mark). Then all values will be surrounded by quotes. However, either calling the Format() method or setting PreserveFormatting to false will be necessary.
  • DefaultValueFormatting - A spectacular property that defines a default appearance of values. The default is "?=$ ;" which causes values look like this: "Key=Value ;comment".
  • ... and much more (totally 16 properties).


What can you do with the Hardcore-Mode? What can you gain?

  • Be faster.
  • Read only the values that you need.
  • Feel like a Hardcore Boss.

Sample scenario #1: You want to extract a single section from an INI file instead of loading a whole file into a dummy ConfigFile class from User-Mode. We will use IniFileReader here. Our goal is to extract the "Mail" section from win.ini to the separate file without loading all other sections.

IniFileReader reader = new IniFileReader("win.ini");
// Find the section without parsing lines before it.

// Get section's content

List<IniFileElement> sectionElements = reader.ReadSection();
// Do not load the rest. Close the stream.


// Write the section.

IniFileWriter writer = new IniFileWriter("mail.ini");

A very good idea is to create an IniFile object from the extracted collection:

IniFile file = IniFile.FromElements(sectionElements)

Such an IniFile would contain one section: the extracted "Mail." This enables a whole set of methods specific to User-Mode, including lazy commenting entries and easy modifying values.

Sample scenario #2: You want to get just ONE value from a file. Let's say that this value is "OLEMessaging" from the "Mail" section in win.ini.

IniFileReader reader = new IniFileReader("win.ini");
// I do not remember how olemessaging's characters exactly look,

// so I set case-sensitivity to false (default true).

IniFileSettings.CaseSensitive = false;
IniFileValue val = reader.GotoValue("olemessaging");
string oleMsg = val.Value;
// ... (do something with oleMsg).

...and so on.


IniFileReader and IniFileWriter are fast. IniFile is a bit slower, although the main slowdown appears while loading a file, not performing operations. For yet higher performance, I have written an additional class in a separate namespace: IniFiles.Light.IniFileLight. It enables parsing and writing of INI files. However, it totally ignores formatting and blank lines. Everything will be written using the following pattern:


It enables commenting values, but only single-line. The usage is similar to the User-Mode:

// Create a new file
Gajatko.IniFiles.Light.IniFileLight light = 
    new Gajatko.IniFiles.Light.IniFileLight();
// Set some data
light.Sections.Add("Data", new Dictionary<string, string>());
light.Sections["Data"].Add("Name", "Mickey");
light.Sections["Data"].Add("Surname", "Mouse");
// Add comments
light.Comments.Add("Data.Surname", "This is a surname");
light.Comments.Add("Data", "This is a section");
// Set a footer
light.Comments.Add("", "Footer");
// Save to a file


;This is a section
;This is a surname

You know the limitations of such a solution, so it's up to you which variant you use. I put the IniFileLight in a separate namespace because if somebody wants to use it, he probably wouldn't like to have all my 10 classes in the auto-completion list.

Format Preserving

Nobody forces you to use this IniFiles's skill; it can run in the background and not bother you. However, if you want to make your INI files look as originally or you are parsing ones which look as originally, I tell you that my code will not loose any content of a file. How much does the parser preserve the format? Here are some samples.

    Key1=  Value1

Look how Key1 looks. After the equality sign there are two spaces. If you add a new value to Section1, it will preserve this appearance and indentation:

    Key1=  Value1
    NewKey=  NewValue

Section1 is a little indented. If you add a new section, it will be a little indented too.

    Key1=  Value1
    NewKey=  NewValue

If you now add a value to Section2, it will look the same as the last value in the previous section:

    Key1=  Value1
    NewKey=  NewValue
    FreshKey=  FreshValue

Let's consider a section with such an appearance:

[ Section1 ]

Then a new added one will follow the template:

[ Section1 ]
[ New Section ]

Also, indentation of comments and blank lines are saved. There are situations when a conflict appears. Here is one of them: If quotes are on (IniFileSettings.QuoteChars = "\""), then we can imagine the following piece:

Key1="Value1" some text

It is obvious that the value of Key1 is 'Value1', not 'Value1" some text' or something like that. The parser knows that, so it interprets ' some text' as a TextOnTheRight. This also will be preserved. However, this behaviour can be changed through the IniFileSettings.AllowTextOnTheRight property.

Format preserving can be turned off by switching IniFileSettings.PreserveFormatting to false. However, you may want to save the indentation of elements. Then call the IniFile.Format(false) method to format everything excluding leading spaces, or IniFile[sectionName].Format(false) to format the specified section.

Download the demo to learn more.


INI files are not used as often as in the old bad DOS times. Now XML is the king. However, they can still be found in various places and sometimes we have to go back to them. My library is the same for INI files as ASP is for HTML controls, where simple tags on the client side have a rich object model on the server. Being very advanced in its core gives it simple and fast access to all INI file features.

Enjoy the IniFiles library!


  • 21 August, 2007 -- Original version posted
  • 2 July, 2008 -- Download updated


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Jacek Gajek
Software Developer
Poland Poland
My name is Jacek Gajek. I have graduated in computer science with a master's degree from Polibuda in Wrocław. I like C# and Monthy Python's sense of humour.

You may also be interested in...

Comments and Discussions

GeneralMy vote of 5 Pin
zssure8-May-13 17:02
memberzssure8-May-13 17:02 
GeneralRe: My vote of 5 Pin
Jacek Gajek8-May-13 23:07
memberJacek Gajek8-May-13 23:07 
QuestionCompile Error StringSplitOptions Pin
Member 838483019-Apr-12 0:38
memberMember 838483019-Apr-12 0:38 
QuestionCase insensitive reading Pin
wardies3-Apr-12 7:00
memberwardies3-Apr-12 7:00 
QuestionBlank line at the beginning of the ini file causes an error: Pin
Member 847678111-Dec-11 5:29
memberMember 847678111-Dec-11 5:29 
QuestionVB.NET Version? Pin
Ken Trock4-Mar-11 5:11
memberKen Trock4-Mar-11 5:11 
AnswerRe: VB.NET Version? Pin
Jacek Gajek5-Mar-11 21:47
memberJacek Gajek5-Mar-11 21:47 
Question'=' Character [modified] Pin
LouisTakePILLz23-Jan-11 19:38
memberLouisTakePILLz23-Jan-11 19:38 
AnswerRe: '=' Character Pin
Jacek Gajek24-Jan-11 2:21
memberJacek Gajek24-Jan-11 2:21 
GeneralRe: '=' Character Pin
LouisTakePILLz24-Jan-11 3:46
memberLouisTakePILLz24-Jan-11 3:46 
GeneralRe: '=' Character Pin
Jacek Gajek24-Jan-11 4:51
memberJacek Gajek24-Jan-11 4:51 
GeneralRe: '=' Character Pin
LouisTakePILLz25-Jan-11 3:13
memberLouisTakePILLz25-Jan-11 3:13 
GeneralRe: '=' Character Pin
LouisTakePILLz27-Jan-11 13:59
memberLouisTakePILLz27-Jan-11 13:59 
GeneralRe: '=' Character Pin
Jacek Gajek28-Jan-11 1:57
memberJacek Gajek28-Jan-11 1:57 
GeneralRe: '=' Character Pin
Jacek Gajek28-Jan-11 2:17
memberJacek Gajek28-Jan-11 2:17 
Generalwill this library work for a inifile without any sections Pin
kiran_sheshadri15-Feb-10 15:23
memberkiran_sheshadri15-Feb-10 15:23 
GeneralRe: will this library work for a inifile without any sections Pin
Jacek Gajek16-Feb-10 22:27
memberJacek Gajek16-Feb-10 22:27 
GeneralMy vote of 1 Pin
abc@opq.com10-Dec-09 0:46
memberabc@opq.com10-Dec-09 0:46 
Generalsimple way :) Pin
Member 281573028-Apr-09 12:35
memberMember 281573028-Apr-09 12:35 
GeneralRe: simple way :) Pin
Jacek Gajek28-Apr-09 13:01
memberJacek Gajek28-Apr-09 13:01 
AnswerRe: simple way :) Pin
Member 281573029-Apr-09 9:48
memberMember 281573029-Apr-09 9:48 
GeneralRe: simple way :) Pin
Jacek Gajek29-Apr-09 10:20
memberJacek Gajek29-Apr-09 10:20 
QuestioniniFile.Header == iniFile[""].Comment ?? Pin
threads3-Feb-09 10:15
memberthreads3-Feb-09 10:15 
AnswerRe: iniFile.Header == iniFile[""].Comment ?? Pin
Jacek Gajek3-Feb-09 11:14
memberJacek Gajek3-Feb-09 11:14 
GeneralRe: iniFile.Header == iniFile[""].Comment ?? Pin
threads3-Feb-09 17:48
memberthreads3-Feb-09 17:48 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web02 | 2.8.190114.1 | Last Updated 2 Jul 2008
Article Copyright 2007 by Jacek Gajek
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid