INI Class for .NET

• Download source and example files - 8.85 Kb

Introduction

This is a class for reading and adjusting INI files. The class utilizes the WritePrivateProfileString and GetPrivateProfileString API calls. Written mainly for legacy support, as a lot applications still use INI files and although there is XML support native to .NET (".config" files), I tend to find that for some circumstances INI files are straightforward and more practical to use.

Using the code

• Add the class file "cINI.cs" to your project / solution.
• Declare and use the class.

  //Read value from INI
  
  aejw.cIni oIni = new aejw.cIni("C:\\INIFile.ini");
  string sRet = oIni.ReadValue("TheSection", 
                     "TheKey", "DefaultReturn");

Functions / Methods

The following examples require the object / class to be declared.

aejw.cIni oIni = new aejw.cIni("C:\\INIFile.ini");

Read Value

//Read value from INI

string sRet = oIni.ReadValue("TheSection", "TheKey", "");

Write Value

//Write value to INI

oIni.WriteValue("TheSection", "TheKey", "TheValue");

Remove Value

//Remove value from INI

oIni.RemoveValue("TheSection", "TheKey");

Read Sections

//Read sections from INI

Array oSections = new Array[0];
oIni.ReadSections(ref oSections);

Read Values (Value names)

//Read values from INI

Array oValues = new Array[0];
oIni.ReadValues(ref oValues);

About the code

Below is a general breakdown of how the code works...

• Referring to the API function...

  All the functions at some stage use a API call. By reading the MSDN Platform SDK material, we get the C++ API call and behavior of the API function...

  DWORD GetPrivateProfileString(
      LPCTSTR lpAppName,
      LPCTSTR lpKeyName,
      LPCTSTR lpDefault,
      LPTSTR  lpReturnedString,
      DWORD   nSize,
      LPCTSTR lpFileName
  );

  Which loosely translates to... (I am using the term loosely on the bases that there are multiple ways of handling the parameters.)

  [DllImport("kernel32", SetLastError=true)]
  private static extern int GetPrivateProfileString(
      string pSection,
      string pKey,
      string pDefault,
      byte[] pValue,
      int    pBufferLen,
      string pFile
  );

  Make note of the LPTSTR to byte[] conversion. The LPTSTR refers to a pointer / reference in memory that the API function will write to, we are going to use a framework function later to collect the text.

• Calling the API function...

  Once the API declaration has been added, we need to create a function to wrap the API function into a C# friendly function.

  private string z_GetString(string psSection, 
                             string psKey, string psDefault){
  
      //Prepare the default return and create 
  
      //a byte array to pass as a pointer
  
      string sRet=psDefault;
      byte[] bRet=new byte[255];
  
      //Call the API function, passing a Section name, value name, default value,
  
      //buffer length (length of the passed byte array) and the ini filename.
  
      int i=GetPrivateProfileString(psSection, psKey, 
                      psDefault, bRet, 255, ls_IniFilename);
  
      //As referred above we use a framework function 
  
      //to collect the string from the byte
  
      //array used as a pointer. Note the 'i' variable 
  
      //is the return from the API call, this
  
      //is passed to the text encoding as the total length of the return.
  
      sRet=System.Text.Encoding.GetEncoding(1252).GetString(bRet, 
                                           0,i).TrimEnd((char)0);
  
      return(sRet);
  
  }

• Using the function...

  Now that we have a API declaration and friendly function, we can call the function at will...

  string sSetting=z_GetString("SectionName","ValueName","");
  string sSetting2=z_GetString("SectionName2", 
                               "ValueName2","DefaultReturn");

History

• 3^rd August 2005 - build 0019
  • Wrote some more general documentation.
  • Changed class filename to 'cINI.cs'.
  • Corrected 'ReadSections' and 'ReadValues'. Rewrote 'z_GetString' function to correctly handle the text encoding and accept chr(0). (Thanks to 'yurij' for reporting the bug).
  • General small bug fixes and improvements.
• 14^th April 2005 - build 0018
  • Corrected issue when returning high ASCII characters, e.g.: '���'
  • Tidied class and documents
• 6^th Feb 2004 - build 0016
  • Corrected bug in 'ReadValue', would return 'char(0)' to the length of the buffer after the value returned.
• 5^th Feb 2004 - build 0015
  • First build posted on CodeProject, based on previous code and dubbed 0015.