A Complete Win32 INI File Utility Class

• Download source - 6 KB

Introduction

While it is no longer the suggested method for storing data by Microsoft, for legacy reasons many applications still need to read and write INI files. Win32 provides several methods for working with INI files, but these methods are not exposed by the .NET Framework. This article presents a simple class to allow a managed application to interact with INI files.

Background

An INI file is a specially formatted text file containing one or more sections. Each section can have one or more settings (or keys). An example file is shown below:

.
[section1]
key1=1
key2=string1
.
.
.

Using the Code

The attached IniFile.cs file contains all the code for the IniFile class. You create a new instance of this class by passing the path of the INI file to read and/or write to the constructor.

//Create a new IniFile object.
IniFile iniFile = new IniFile(@"c:\boot.ini");

Reading from an INI File

Similar to the System.Data.DataReader.IDataReader interface, the IniFile class provides several methods for reading different types of data from an INI file. Each of these methods takes the form "GetX", where X is the requested data type of the return value. For example, to read a System.Int32 value from your INI file, you use the GetInt32 method.

//Read an Int16 value from an INI file.
short value1 = iniFile.GetInt16("section1", "key1", 0);

//Read an Int32 value from an INI file.
int value2 = iniFile.GetInt32("section1", "key2", 0);

//Read a String from an INI file.
string value3 = iniFile.GetString("section1", "key3", "default value");

//Read an Double value from an INI file.
double value4 = iniFile.GetDouble("section1", "key4", 0.0);

//Read an Boolean value from an INI file.
bool value5 = iniFile.GetBoolean(quot;section1", "key5", true);

As shown above, each of these methods takes three parameters. The first specifies the name of the section to read from. The second specifies the specific key to read from. The final parameter specifies the value to return if the section/key is not found. Please note that string values are limited to 32KB or less. Attempting to read a setting that is more than 32KB in length will result in the data being truncated to 32KB.

The IniFile class also provides methods to enumerate the list of sections or keys in a file. Each of these methods returns an array of strings.

//Get the list of sections in the INI file.
string [] sectionNames = iniFile.GetSectionNames();

//Get the list of keys in the first section.
string [] keyNames = iniFile.GetKeyNames(sectionNames[0]);

Finally, the IniFile class provides methods that allow a caller to read all of the keys in a given section at once. This functionality is provided by two functions: GetSectionValues and GetSectionValuesAsList.

GetSectionValues is the more convenient of the two. It returns all the key/value pairs in a section as a Dictionary<string, string> object. This makes it very easy to get the value of several properties at one time.

//Get the key/value pairs in a section of the INI file as a Dictionary.

//Get the key/values in section1.
Dictionary<string, string> sectionValues = iniFile.GetSectionValues("section1");

string value1 = sectionValues["key1"];
string value2 = sectionValues["key2"];

If a section contains more than one value with the same key, GetSectionValues always returns the first one in the file. If you need to be able to get all the values in a section no matter what the key names are, you can use the GetSectionValuesAsList method.

//Get the key/value pairs in a section of the INI file as a List.

//Get the key/values in section1.
List<KeyValuePair<string, string>> sectionValues;

sectionValues = iniFile.GetSectionValuesAsList("section1");

foreach (KeyValuePair<string, string> pair in sectionValues)
{
    //Process the keys here...
}

Both of these methods share the same 32KB limit as GetString. If your section can contain more than 32KB of data, read each setting separately.

Writing to an INI File

The IniFile class also provides methods to write to an INI file. The various overloads of the WriteValue method allow the caller to write strings, integers, or doubles to an INI file. Each of these functions takes three parameters. The first specifies the name of the section to write to. The second specifies the specific key to write to. The final parameter specifies the new value for the key. If the section and key already exist, the existing value is overwritten. If the specified section or key do not exist, they are automatically created.

//Write a string to the iniFile
iniFile.WriteValue("section1", "key2", "Test value");

//Write a Int32 to the iniFile.
iniFile.WriteValue("section1", "key1", 128);

//Write a Double to the iniFile.
iniFile.WriteValue("section1", "key1", 42.8);

//Write a Boolean to the iniFile.
iniFile.WriteValue("section1", "key1", true);

Deleting Data from an INI File

The IniFile class provides methods to delete keys and sections from an INI file. Use DeleteKey to delete a specific key and DeleteSection to delete a complete section from an INI file.

//Delete key2 from section1
iniFile.DeleteKey("section1", "key2");

//Delete section2 (including all keys)
iniFile.DeleteSection("section2");

History

• 05/28/2014
• Corrected return type of GetInt16
• Added GetBoolean and new WriteValue method to write boolean values
• GetDouble no longer throws an exception if the text value of the key could not be parsed. It now returns the default value in this case.
• 11/18/2013
• Fixed some spelling errors in comments. Added documentation about exceptions the constructor can throw.
• 11/19/2007
• Added parameter checking
• Added DeleteKey and DeleteSection
• Added notes about the 32KB limitation for most methods
• 11/19/2007
• Fixed XML comments
• Added GetSectionValues and GetSectionValuesAsList
• 8/14/2007 - Initial version