C# 如何实现完整的INI文件读写类

作者: 魔法软糖

日期: 2020-02-27

引言

*************************************

.ini 文件是Initialization File的缩写，即配置文件 。是windows的系统配置文件所采用的存储格式。

它具有方便易用的特点，和注册表的键值有着类似的功能，各类应用程序也经常使用INI保存各种配置和选项。

在简单只需要读取的场合，调用WINDOWS API就行，但在复杂的需要可视化编辑时，就需要建立自己的处理类了。

 

如何实现自己的INI类

首先我们需要了解

◇  INI的格式

 

◇  典型INI文件

;项目注释
[.ShellClassInfo]
InfoTip=有图标的文件夹
;图标资源
IconResource="C:Windowssystem32SHELL32.dll",4
#文件夹视图
[ViewState]
Mode=
Vid=
FolderType=General
#尾部注释

 一个典型INI文件由节、注释和节下面的项组成，而项为键=值的形式。

INI文件的注释符号有两种，规范为;分号，实际有些地方用#井号。

◇  保留注释

为了在修改INI文件时不丢失任何信息，所以需要保存INI文件中所有有效元素、包括注释甚至是无效行。

为了实现这个目的，将所有注释和无效行都归属于它之后的有效元素。

以上面的desktop.ini为例，

• 第一行 ;项目注释归属于[.ShellClassInfo]节
• 第四行;图标资源归属于IconResource=项
• #文件夹视图归属于[ViewState]节
• 最后的#尾部注释归属于整个INI文档的EndText

◇  INIItem类

表示INI文件中节点下面的项，它拥有三个属性：名称Name、值Value和注释Comment

    /// <summary>
    /// 拥有名称、值和注释
    /// </summary>
    public class INIItem {
        /// <summary>
        /// 实例化INIItem。指定名称、值和注释。
        /// </summary>
        /// <param name="vName"></param>
        /// <param name="vValue"></param>
        /// <param name="vComment"></param>
        public INIItem(string vName, string vValue, string vComment = "") {
            Name = vName;
            Value = vValue;
            Comment = vComment;
        }
        /// <summary>
        /// 项名称。例如 Color = 202,104,0 中的 Color
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 值内容。例如 Color = 202,104,0 中的 202,104,0
        /// </summary>
        public string Value { get; set; }
        /// <summary>
        /// 位于前面的所有注释行。一般以 ; 开头
        /// </summary>
        public string Comment { get; set; }
        /// <summary>
        /// 返回 INIItem 的文本形式。〈<see cref="string"/>〉
        /// <para>Name=Value</para>
        /// </summary>
        /// <returns>〈string〉返回 INIItem 的文本形式。</returns>
        public override string ToString() {
            return Name + INI.U等号 + Value;
        }        
    }

◇  ININode类

表示INI文件中的一个节点，它拥有项列表List{Of INIItem}、名称Name和注释Comment。

    /// <summary>
    /// 表示INI文件的一个节点，它拥有一个项目列表，还拥有名称和注释
    /// <para></para>
    /// </summary>
    public class ININode {
        /// <summary>
        /// 实例化ININode。指定初始的名称和注释。
        /// </summary>
        /// <param name="vName"></param>
        /// <param name="vComment"></param>
        public ININode(string vName, string vComment) { Name = vName; Comment = vComment; Items = new List<INIItem>(); }
        /// <summary>
        /// 节点名称。例如 [Config]
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 位于前面的所有注释行。一般以 ; 开头
        /// </summary>
        public string Comment { get; set; }
        /// <summary>
        /// 含有的项列表
        /// </summary>
        public List<INIItem> Items { get; set; }
        /// <summary>
        /// 向本节点添加新项。
        /// </summary>
        /// <param name="vName"></param>
        /// <param name="vValue"></param>
        /// <param name="vComment"></param>
        /// <returns></returns>
        public INIItem New(string vName, string vValue, string vComment = "") {
            var k = new INIItem(vName, vValue, vComment);
            Items.Add(k);
            return k;
        }
        /// <summary>
        /// 返回 ININode的文本形式。〈<see cref="string"/>〉
        /// <para>[Name]</para>
        /// </summary>
        /// <returns>〈string〉返回 ININode 的文本形式。</returns>
        public override string ToString() {
            return INI.U左括号 + Name + INI.U右括号;
        }
    }

◇  INI类

它表示整个INI文件的全部内,拥有List{Of ININode}、EndText、FileName、StartLine等属性

    /// <summary>
    /// 表示INI文件。拥有读取和写入文件的方法。
    /// <para>储存在 <see cref="List{ININode}"/>&lt;<see cref="ININode"/>&gt;</para>
    /// </summary>
    public class INI {
        /// <summary>
        /// 实例化INI文件。
        /// </summary>
        public INI() { }

        #region "↓全局常量"
        /// <summary>注释的标准符号</summary>
        public static string U注释 = ";";
        /// <summary>注释的标准符号2</summary>
        public static string U注释2 = "#";
        /// <summary>节左括号的标准符号</summary>
        public static string U左括号 = "[";
        /// <summary>节右括号的标准符号</summary>
        public static string U右括号 = "]";
        /// <summary>连接项和值的标准符号</summary>
        public static string U等号 = "=";
        /// <summary>读取或写入时忽略无意义的备注行(不包括注释)。</summary>
        public static bool 忽略备注 = false;
        /// <summary>读取的上个文件的有效行数(不包括注释)。</summary>
        public static int 上次读取的有效行数 = 0;
        #endregion

        /// <summary>
        /// 所有节点
        /// <para>每个节点含有项、值和注释，当项名称为空字符串时，整条语句视为注释</para>
        /// </summary>
        public List<ININode> Nodes { get; set; } = new List<ININode>();
        /// <summary>
        /// 附加在INI文件后无意义的文本
        /// </summary>
        public string EndText { get; set; } = "";
        /// <summary>
        /// 附加在INI文件第一行的作者信息等文本
        /// <para>其中的换行符将被替换为两个空格</para>
        /// </summary>
        public string StartLine { get; set; } = "";
        /// <summary>
        /// 读取INI时获得的FileName。
        /// <para>写入文档时可以使用这个名字，也可以不使用这个名字。</para>
        /// </summary>
        public string FileName { get; set; } = "";
        /// <summary>
        /// 向本INI文件添加新节点。
        /// </summary>
        /// <param name="vName"></param>
        /// <param name="vComment"></param>
        /// <returns></returns>
        public ININode New(string vName, string vComment = "") {
            var k = new ININode(vName, vComment);
            Nodes.Add(k);
            return k;
        }
    }

如何写入INI文件

1. 首先遍历每个节点，写入节点的注释和节点名称（套个括号）
2. 然后遍历每个节点下面的项，写入项的注释和项的名称=值。
3. 写入尾部注释

以下是写入代码

        #region "写入文件"

        /// <summary>将文档写入指定路径
        /// </summary>
        /// <param name="path">指定路径</param>
        public bool 写入文档(string path, Encoding encoding = null) {
            try {
                if (encoding == null) { encoding = Encoding.Default; }
                using (StreamWriter SW = new StreamWriter(path)) {
                    SW.Write(ToString());
                }
            } catch (Exception) {
                return false;
            }       
            return true;
        }
        /// <summary>
        /// 将INI文档转化为文本格式，会生成整个文档。
        /// <para>注意：较大的文档可能会耗费大量时间</para>
        /// </summary>
        /// <returns></returns>
        public override string ToString() {
            StringBuilder sb = new StringBuilder();
            if (StartLine.Length > 0) { sb.AppendLine(StartLine.Replace("
", "  ")); }
            for (int i = 0; i < Nodes.Count; i++) {
                var node = Nodes[i];
                if (忽略备注 == false) { sb.Append(node.Comment); }
                sb.AppendLine(node.ToString());
                for (int j = 0; j < node.Items.Count; j++) {
                    var item = node.Items[j];
                    if (忽略备注 == false) { sb.Append(item.Comment); }
                    sb.AppendLine(item.ToString());
                }
            }
            if (EndText.Length > 0) { sb.AppendLine(EndText); }         
            return sb.ToString();
        }

        #endregion

如何读取INI文件

读取通常比写入复杂。软糖的代码也是逐行检查，多次调试才完成。

流程如下：

1. 首先定义一些局部变量来记录当前分析的节、项、已经累积的备注、是否为有效行。
2. 逐行读取，首先判断是否开头为;或#，如果是，添加到备注，加回车符，设为有效行。
3. 判断开头是否为[，如果是则作为节来读取，进一步分析，如果[A]这种形式，设置当前节，设为有效行，如果[B缺少反括号，进行下一步流程，尚无法判断是[B=K这种项还是纯粹无意义的无效行。
4. 判断是否含有=，如果是则作为项来读取
5. 如果未标记为有效行，通通加入备注。
6. 如果读完全文，备注不为空，则加入到INI.EndText中作为结尾注释。

代码

 #region "读取文件"
        /// <summary>
        /// 从指定路径和字符编码的文件中读取文档内容，以此生成本文档。
        /// </summary>
        /// <param name="路径">完整的路径字符串</param>
        /// <param name="encoding">编码格式：默认自动识别。（对于无bom可能识别错误）</param>
        public bool 读取文档(string 路径, Encoding encoding = null) {
            if (File.Exists(路径) == false) { return false; }
            try {
                if (encoding == null) { encoding = TXT.GetFileEncodeType(路径); }
                using (StreamReader SR = new StreamReader(路径, encoding)) {
                    bool 返回结果 = 读取文档(new StringReader(SR.ReadToEnd()));
                    SR.Close();
                    return 返回结果;
                }
            } catch (Exception) {
                return false;
            }
        }

        /// <summary>
        /// 从 <see cref="StringReader"/> 中读取文档内容，以此生成本文档。
        /// </summary>  
        /// <param name="MyStringReader">StringReader，可以由string或StreamReader.ReadToEnd()来生成。</param>
        /// <returns>〈bool〉返回是否读取成功。</returns>
        public bool 读取文档(StringReader MyStringReader) {
            /// <summary>正在分析的节</summary>
            ININode 当前节 = null;
            /// <summary>正在分析的项</summary>
            INIItem 当前项 = null;
            /// <summary>正在分析的节名</summary>
            string 当前节名 = null;
            /// <summary>正在分析的项名</summary>
            string 当前项名 = null;
            /// <summary>累计读取的属性行的计数</summary>
            int 计数 = 0;
            /// <summary>该行是合法有效的行，还是无法识别的行。(无法识别作为备注处理)</summary>
            bool 有效行 = false;
            /// <summary>该行去掉空格和Tab符的文本长度</summary>
            int 有效文本长度;
            /// <summary>每个实体前的注释</summary>
            string 备注 = "";
            // * 循环读取每行内容 *
            while (true) {
                string 行文本 = MyStringReader.ReadLine();
                if (行文本 == null) {  if (备注.Length > 0) { EndText = 备注; } 上次读取的有效行数 = 计数; break; } else {
                    string 行;

                    有效行 = false;
                    // * 获取 去掉空格和Tab符的文本 *
                    行 = 行文本.Trim(' ', '	');
                    // * 获取 去掉空格和Tab符的文本的长度 *
                    有效文本长度 = 行.Length;
                    // * 检测注释符 *
                    if (行文本.Contains(U注释)) {
                        int 注释位置 = 行文本.IndexOf(U注释);
                        行 = 行文本.Substring(0, 注释位置);
                        int 注释开始位置 = 注释位置 + U注释.Length - 1;
                        int 注释长度 = 行文本.Length - 注释开始位置;
                        if (注释长度 > 0) {
                            if (备注.Length > 0) { 备注 += "
"; }
                            备注 += 行文本.Substring(注释开始位置, 注释长度);
                        }
                        有效行 = true;
                    }
                    if (行文本.Contains(U注释2)) {
                        int 注释位置 = 行文本.IndexOf(U注释2);
                        行 = 行文本.Substring(0, 注释位置);
                        int 注释开始位置 = 注释位置 + U注释2.Length - 1;
                        int 注释长度 = 行文本.Length - 注释开始位置;
                        if (注释长度 > 0) {
                            if (备注.Length > 0) { 备注 += "
"; }
                            备注 += 行文本.Substring(注释开始位置, 注释长度);
                        }
                        有效行 = true;
                    }
                    // * 检查开头字符 *
                    if (行.Length >= 2) {
                        //[类型定义]====首字符：U节首[
                        if (行[0] == U左括号[0]) {
                            int 右括号位置 = 行.IndexOf(U右括号[0], 2);
                            if (右括号位置 > 1) {
                                当前节名 = 行.Substring(1, 右括号位置 - 1);
                                当前节 = New(当前节名, 备注);
                                备注 = "";
                                计数 += 1;
                                有效行 = true;
                            }
                        }
                        //项定义====含有等号的行
                        // -> 获取赋值符号位置
                        int 赋值符位置 = 行.IndexOf(U等号, 2);
                        if (赋值符位置 > 1) {
                            // -> 获得名称和值，并新建项
                            当前项名 = 行.Substring(0, 赋值符位置).Trim(' ', '	');
                            string 值 = 行.Substring(赋值符位置 + 1, 行.Length - 赋值符位置 - 1).Trim(' ', '	');
                            if (当前节 != null) {
                                当前项 = 当前节.New(当前项名, 值, 备注);
                                备注 = "";
                                计数 += 1;
                                有效行 = true;
                            }                                                      
                        }
                    }
                    // * 无效行作为备注处理 *
                    if (有效行 == false) {
                        if (忽略备注 == false) {
                            if (行文本.Length == 0) { 备注 += "
"; } else { 备注 += 行文本 + "
"; }
                        }
                    }
                }                             
            }
            return true;
        }

        #endregion

◇  编码问题

/// <summary>
        /// 通过文件的头部开始的两个字节来区分一个文件属于哪种编码。
        /// 如果文件长度不足2字节，则返回null
        /// 当FF FE时，是Unicode；
        /// 当FE FF时，是BigEndianUnicode；
        /// 当EF BB时，是UTF-8；
        /// 当它不为这些时，则是ANSI编码。
        /// </summary>
        public static Encoding GetFileEncodeType(string filename) {
            FileStream fs = new FileStream(filename, FileMode.Open, FileAccess.Read);
            BinaryReader br = new BinaryReader(fs);
            Byte[] buffer = br.ReadBytes(2);
            if (buffer.Length < 2) { return null; }
            if (buffer[0] >= 0xEF) {
                if (buffer[0] == 0xEF && buffer[1] == 0xBB) {
                    return Encoding.UTF8;
                } else if (buffer[0] == 0xFE && buffer[1] == 0xFF) {
                    return Encoding.BigEndianUnicode;
                } else if (buffer[0] == 0xFF && buffer[1] == 0xFE) {
                    return Encoding.Unicode;
                } else {
                    return Encoding.Default;
                }
            } else {
                return Encoding.Default;
            }
        }

窗体读取INI演示

 ◇  演示效果

 

◇ INIListView类

用一个辅助类将INI文件内容显示到ListView来展现效果。

给每个节点添加一个Group组，将节点本身和下辖的项都放进组。

当鼠标选中某项时，判断该item的Key和Group即可知道它属于哪个节点，名称是什么。

    public class INIListView {
        public ListView 视图;
        public Color 节颜色 = Color.FromArgb(0, 153, 153);
        public Color 节底色 = Color.FromArgb(255, 255, 255);
        public void 绑定控件(ListView ListView) {
            视图 = ListView;
            初始化();            
        }
        public void 载入数据(INI ini) {
            初始化组(ini);
            初始化数据(ini);
        }

        private void 初始化() {
            视图.View = View.Tile;
            视图.ShowGroups = true;
            初始化列();
        }

        private void 初始化列() {
            视图.Columns.Clear();
            视图.Columns.Add("A", "名称", 220);
            视图.Columns.Add("B", "值", 300);
            视图.Columns.Add("C", "注释", 440);
        }
        private void 初始化组(INI ini) {
            if (ini == null) { return; }
            for (int i = 0; i < ini.Nodes.Count; i++) {
                string nodeName = ini.Nodes[i].Name;
                int cc = ini.Nodes[i].Items.Count;
                string nodeTitle = string.Format("{0} ({1})", nodeName, cc);
                视图.Groups.Add(nodeName, nodeTitle);
            }
        }

        private void 初始化数据(INI ini) {
            视图.Items.Clear();

            if (ini == null) { return; }
            for (int i = 0; i < ini.Nodes.Count; i++) {
                string nodeName = ini.Nodes[i].Name;               
                var nodeitem = 视图.Items.Add(nodeName, "["+nodeName+"]",0);
                nodeitem.ForeColor = 节颜色;
                nodeitem.BackColor = 节底色;
         
                nodeitem.Group = 视图.Groups[nodeName];
               

                for (int j = 0; j < ini.Nodes[i].Items.Count; j++) {
                    var iniitem = ini.Nodes[i].Items[j];
                    string name = iniitem.Name;
                    string value = iniitem.Value;
                    string comment = iniitem.Comment;
                    var item = 视图.Items.Add(name, name);
                    item.Group = 视图.Groups[nodeName];
                    item.SubItems.Add(value);
                    item.SubItems.Add(comment);
                }
            }
        }

    }

窗体上拖一个ListView(数据视图)和OpenFileDialog(openINIFileDialog)、和Button(按钮_读取文件)

    public partial class 编辑窗体 : Form {
        INIListView INIListView = new INIListView();
        INI 当前文档;
        

        public 编辑窗体() {
            InitializeComponent();
        }

        private void 编辑窗体_Load(object sender, EventArgs e) {
            Width = 1280;
            Height = 720;
            初始化数据视图();
            openINIFileDialog.InitialDirectory = Environment.CurrentDirectory;
        }
        private void 初始化数据视图() {
            INIListView.绑定控件(数据视图);
        }

        private void 按钮_读取文件_Click(object sender, EventArgs e) {
            var result = openINIFileDialog.ShowDialog();
            if (result == DialogResult.OK) {
                当前文档 = new INI();
                var 读取结果 = 当前文档.读取文档(openINIFileDialog.FileName);
                INIListView.载入数据(当前文档);
            } 


        }

        private void 视图_1_Click(object sender, EventArgs e) {
            数据视图.View = View.Details;            
        }

        private void 视图_2_Click(object sender, EventArgs e) {
            数据视图.View = View.Tile;
        }

        private void 视图_3_Click(object sender, EventArgs e) {
            数据视图.View = View.List;
        }

        private void 视图_4_Click(object sender, EventArgs e) {
            数据视图.View = View.SmallIcon;
        }

        private void 视图_5_Click(object sender, EventArgs e) {
            数据视图.View = View.LargeIcon;
        }
    }

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

结语：本文实现了INI文件的构造、读取和写入。

实际上通过扩展可以实现更强大的数据格式。