Jealous that someone (Todd Davis) thought of it first, I was recently inspired to do some hacking of my own and put together my own .NET 2.0
INIFile class. Like Todd's, mine reads the file directly rather than relying on the Windows kernel to do it.
INIFile class parses a .ini file into
Key classes upon setting its
Contents property. Getting the property reconstructs the .ini file from the said
Key classes. The result is a parser that automatically reformats the .ini file for you (as a side effect, really).
INIFile object maintains a
List (Of Section) collection (aptly titled
Sections), and each
Section has a
Keys collection (
List (Of Key)).
Files are not directly edited except when loading and saving. In other words, the .ini file is edited entirely in memory.
In addition to using collections to edit the information, I also went about adding some higher level methods to the
INIFile class. These operate on the
Section.Keys collections internally, but don't require a
Section class or a
Key class as a parameter, opting instead for the more traditional strings.
All of the high level editing functions also have a
Shared counterpart that takes a filename parameter. This instantiates the
INIFile class, loads the file, performs the operation, saves the file, and returns. For quick edits, this is fine. But for data intensive operations (i.e., thousands of sections or keys), it is recommended that the
Shared editing functions (as well as the other high level editing functions, in general) not be used. For those kinds of things, it's always faster to use the
In addition to editing sections and keys, comments can be edited, and keys can be added to the top of the file outside of any section. A comment is any line that begins with a comment character (usually either a ; or a #). Creating a comment is as simple as creating a new key with only one parameter. Internally, a comment is simply a
Key object with
IsComment set to
Value set to the text of the comment (without the comment character). The
Name field is ignored for comments, and is not output through the
If the *first
Section in the
Sections collection has its
Name field set to
Nothing, it indicates the top of the file, and contains the key and comments shown there.
The entire source code for the
INIFile class has XML documentation, and should be ready for NDoc (whenever they get .NET 2.0 support working).
*See Known Issues.
Non-INI File Usage
INIFile is written gives developers a bit more of a choice in handling .ini files than the built in Windows functions do. Typically, .ini files are for storing settings and other initialization data, hence the name initialization file. They have a pretty standard format.
INIFile class has a few properties that allow the developer to change the parsing characters:
INIFile.Contents property parses directly, the
INIFile class does not require a file actually be loaded or saved. This allows the data to be used in other ways. For example, you now have a formatter (other than XML) that uses a very simple syntax that can be easily sent over a network connection.
Included in the Zip file is a demo application that illustrates most of the capabilities of the
INIFile class. It can load and save .ini files as well as create them from scratch. It can view, add, and remove sections. It can view, edit, and remove comments. It can also view, add, edit, and remove keys.
The upper box is the value of the
Contents property. The lower box lets you enter (or paste) a .ini file. The Parse button sets the
INIFile.Contents property to contain the contents of the lower textbox, then outputs it again to the upper text box. It also sets the contents of the list boxes on the other tab page.
Editing the contents of either the sections or keys list boxes updates the contents of the
INIFile class immediately.
This program demonstrates the use of collections. It does not demonstrate the higher level editing functions or the shared editing functions.
Section in the
Sections collection other than the first one has its name set to
Nothing, the value of the
Content property will omit the section header for that section. When re-parsing the output, the keys will be merged with the previous section. If you need a section with a blank title that is still output (usually as ), set the
Name property to an empty string (i.e.,
In some cases,
INIFile.FindKey (and several other methods that rely on this method) throws a
KeyNotFoundException even when the key exists. This is because only the first matching section is searched for the key. If it's not found in the first matching section, the call fails even if there are more than one matching sections. Instead, consider using the
Keys collections. Also consider not using duplicate sections.
Name field of a
IsComment property is set to
True (a comment key) is not output through the
INIFile.Contents property. This will result in the value being lost when the .ini file is later read back from a file or some other source.
INI Contents tab
No known issues.
Currently, the demo app cannot create a section for the top of the file (section for keys and comments outside of a section). It can, however, delete them and edit the keys and comments. The demo app cannot convert between a comment and a key. The demo app cannot rename an existing section without losing the keys it stores. These issues are limitations of the demo app, not the
INIFile class. They can be fixed by manual editing under the INI Contents tab.
The caption bar of the application reads "Form1" rather than a more creative name such as "INIFile Class Demonstration". This particular problem stems from the fact that I am lazy and have (as of current writing) neglected to change it.
INIFile class and its demo app are both protected under the Creative Commons Attribution-ShareAlike 2.5 license. The full license text is available here. A non-legalese version is also available, here.