C#读写INI配置文件的技术方案与实践指南
作者：加号3
INI（Initialization）文件作为一种经典的配置文件格式，凭借其结构简单、可读性强、易于人工编辑的特点，在 Windows 开发生态中拥有长久的生命力。尽管 XML、JSON 等现代格式日益流行，但在桌面应用、系统工具、遗留系统维护等场景中，INI 文件依然广泛存在。本文将从技术原理、实现路径、设计考量和最佳实践四个层面，系统阐述在 C# 中进行 INI 文件读写操作的核心知识。
一、INI 文件的结构特性与适用场景
INI 文件采用分段键值对的组织形式，以方括号标识节（Section），以等号分隔键（Key）与值（Value），以分号或井号引导注释行。这种扁平化的结构决定了它最适合存储简单的层级配置，例如应用程序的窗口位置、最近打开的文件列表、用户偏好设置等。
[Database] Server=192.168.1.100 Port=3306 ; 生产环境使用加密连接 Encrypt=true [UI] Theme=Dark Language=zh-CN
与 JSON 相比，INI 不支持嵌套对象和数组类型；与 XML 相比，INI 缺乏 Schema 验证和命名空间机制。这些局限性恰恰也是它的优势所在——对于非技术人员而言，INI 文件的修改门槛极低，无需担心括号匹配或标签闭合问题。因此，在需要终端用户手动调整配置的场景中，INI 仍然是合理的选择。
二、基于 Windows API 的传统方案
Windows 操作系统原生提供了读写 INI 文件的 API 函数，C# 可以通过平台调用（P/Invoke）机制直接使用这些函数。这是最贴近系统底层的实现方式，也是许多遗留系统采用的标准做法。
该方案的核心优势在于与 Windows 生态的无缝集成。系统 API 会自动处理文件的编码、缓存和并发访问，开发者无需关心底层细节。同时，API 支持按节和键进行精确读写，以及一次性读取整个节的键值集合，操作粒度灵活。
然而，P/Invoke 方案存在明显的平台绑定问题。这些 API 仅在 Windows 环境下可用，一旦应用需要迁移到 Linux 或 macOS 平台，相关代码将全部失效。此外，API 的字符串处理基于旧版 ANSI 编码，在涉及中文等多字节字符时可能遇到编码兼容性困扰。因此，该方案更适合确定长期运行在 Windows 环境下的传统桌面应用。
三、并发访问与文件同步的考量
配置文件往往被多个进程或同一进程的多线程同时访问，读写安全是不可回避的设计要点。
Windows API 方案依赖操作系统的文件锁机制，在并发场景下表现稳定。而自定义解析方案必须显式处理同步问题。常见的做法是在配置管理类内部维护一个读写锁，所有文件操作都经过锁保护。对于读多写少的场景，可以采用乐观锁策略：读取时不加锁，写入时先读取整个文件、合并变更、再原子写入，利用文件系统的原子写入特性避免脏数据。
另一个关键细节是配置变更的实时感知。如果应用需要响应外部对 INI 文件的手动修改，可以通过文件系统监视器监听文件的变更事件，在检测到修改时自动重新加载配置，实现运行时的动态刷新。
四、代码实现
4.1、接口实现
/// <summary>
/// 读配置文件方法的6个参数：所在的分区（section）、 键值、 初始缺省值、 StringBuilder、 参数长度上限 、配置文件路径
/// </summary>
/// <param name="section"></param>
/// <param name="key"></param>
/// <param name="defaultValue"></param>
/// <param name="retVal"></param>
/// <param name="size"></param>
/// <param name="filePath"></param>
/// <returns></returns>
[DllImport("kernel32")]
public static extern long GetPrivateProfileString(string section, string key, string defaultValue, StringBuilder retVal, int size, string filePath);
/// <summary>
/// 写入配置文件方法的4个参数： 所在的分区（section）、 键值、 参数值、 配置文件路径
/// </summary>
/// <param name="section"></param>
/// <param name="key"></param>
/// <param name="value"></param>
/// <param name="filePath"></param>
/// <returns></returns>
[DllImport("kernel32")]
private static extern long WritePrivateProfileString(string section, string key, string value, string filePath);
4.2、读文件信息
/// <summary>
/// 读文件信息
/// </summary>
/// <param name="section">节点</param>
/// <param name="key">key值</param>
/// <returns></returns>
public static string GetFileIniValue(string section, string key,string FilePath)
{
try
{
if (File.Exists(FilePath)) //检查是否有配置文件，并且配置文件内是否有相关数据。
{
StringBuilder sb = new StringBuilder(255);
GetPrivateProfileString(section, key, "配置文件不存在，读取未成功!", sb, 255, FilePath);
return sb.ToString();
}
}
catch (Exception ex)
{
}
return string.Empty;
}
4.3、写INI配置文件
/// <summary>
/// 写INI配置文件
/// </summary>
/// <param name="section">节点</param>
/// <param name="key">key值</param>
/// <param name="value">值</param>
public static bool SetFileIniValue(string section, string key, string value, string FilePath)
{
bool bRet;
try
{
bRet = WritePrivateProfileString(section, key, value, FilePath) > 0;
}
catch (Exception ex)
{
bRet = false;
}
return bRet;
}
五、类型安全与配置校验
原始的 INI 文件只存储字符串，但应用代码通常需要整数、布尔值、枚举等强类型数据。配置管理层的价值很大程度上体现在类型转换与校验的封装上。
良好的设计应当为每种常用类型提供专门的读取方法，并在转换失败时抛出具有明确上下文的异常，而不是返回模糊的默认值。更进一步，可以引入配置 Schema 的概念，在应用启动时对整份配置文件进行校验，确保所有必需的键都存在、所有值都符合预期的格式和范围。这种前置校验能够将配置错误拦截在启动阶段，避免在运行中途因配置异常引发难以定位的故障。
六、工程实践与陷阱规避
路径管理：INI 文件位置决定其生命周期。程序目录下的配置为只读模板；用户应用数据目录（Environment.SpecialFolder.ApplicationData）存储用户个性化设置；临时目录适合缓存配置。使用 Path.Combine 构建跨平台路径，避免硬编码分隔符。
大小写敏感性：Windows API 默认不区分大小写，但 Linux 文件系统敏感。托管实现应明确设计策略：通常节名和键名不区分大小写（符合 Windows 传统），但值内容保持原样。字典存储时使用 StringComparer.OrdinalIgnoreCase 确保一致行为。
空值与空节处理：明确区分空字符串（Key=）与键不存在。空节（[EmptySection] 无内容）应保留结构还是自动清理？根据场景决定：用户手动编辑时应保留空节作为占位符；程序自动生成时可清理以减小文件体积。
注释保留难题：解析-修改-保存流程常导致注释丢失。若需保留用户注释，必须设计 AST（抽象语法树）级别的解析器，将注释节点关联到相邻的节或键。简单的字典结构无法保存注释信息，这是许多 INI 库的功能短板。
七、知识扩展
INI 文件是一种简单的配置文件格式，由节（Section）、键（Key）和值（Value）组成，常用于存储应用程序的初始化设置。
INI 文件的基本结构
; 这是注释 [Database] Server=localhost Port=3306 User=root [Logging] Level=Info File=app.log
C# 中读写 INI 的常见方案
方案一：调用 Windows API（推荐，简单高效）
Windows 提供了 kernel32.dll 中的两个专用函数：
WritePrivateProfileString：写入值GetPrivateProfileString：读取值
注意：这些函数只能操作绝对路径下的文件，且对文件大小有一定限制（通常 64KB 以内）。
完整封装类：
using System;
using System.IO;
using System.Runtime.InteropServices;
using System.Text;
public class IniHelper
{
private string filePath;
/// <summary>
/// 初始化 INI 文件操作类
/// </summary>
/// <param name="path">INI 文件路径（绝对路径）</param>
public IniHelper(string path)
{
filePath = Path.GetFullPath(path);
}
[DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
private static extern int GetPrivateProfileString(
string lpAppName,
string lpKeyName,
string lpDefault,
StringBuilder lpReturnedString,
int nSize,
string lpFileName);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
private static extern int WritePrivateProfileString(
string lpAppName,
string lpKeyName,
string lpString,
string lpFileName);
/// <summary>
/// 读取字符串值
/// </summary>
/// <param name="section">节名</param>
/// <param name="key">键名</param>
/// <param name="defaultValue">默认值（读取失败时返回）</param>
public string ReadString(string section, string key, string defaultValue = "")
{
StringBuilder sb = new StringBuilder(1024);
GetPrivateProfileString(section, key, defaultValue, sb, sb.Capacity, filePath);
return sb.ToString();
}
/// <summary>
/// 写入字符串值
/// </summary>
/// <param name="section">节名</param>
/// <param name="key">键名</param>
/// <param name="value">要写入的值</param>
/// <returns>是否成功</returns>
public bool WriteString(string section, string key, string value)
{
int result = WritePrivateProfileString(section, key, value, filePath);
return result != 0;
}
/// <summary>
/// 读取整数
/// </summary>
public int ReadInt(string section, string key, int defaultValue = 0)
{
string str = ReadString(section, key, defaultValue.ToString());
return int.TryParse(str, out int val) ? val : defaultValue;
}
/// <summary>
/// 写入整数
/// </summary>
public bool WriteInt(string section, string key, int value)
{
return WriteString(section, key, value.ToString());
}
/// <summary>
/// 读取布尔值（支持 true/false、1/0、yes/no）
/// </summary>
public bool ReadBool(string section, string key, bool defaultValue = false)
{
string str = ReadString(section, key, defaultValue.ToString()).ToLower();
return str == "true" || str == "1" || str == "yes";
}
/// <summary>
/// 写入布尔值
/// </summary>
public bool WriteBool(string section, string key, bool value)
{
return WriteString(section, key, value ? "true" : "false");
}
/// <summary>
/// 删除指定键
/// </summary>
public bool DeleteKey(string section, string key)
{
return WritePrivateProfileString(section, key, null, filePath) != 0;
}
/// <summary>
/// 删除整个节
/// </summary>
public bool DeleteSection(string section)
{
return WritePrivateProfileString(section, null, null, filePath) != 0;
}
/// <summary>
/// 获取节下所有键名
/// </summary>
public string[] GetKeys(string section)
{
StringBuilder sb = new StringBuilder(32768);
GetPrivateProfileString(section, null, null, sb, sb.Capacity, filePath);
return sb.ToString().TrimEnd('\0').Split('\0', StringSplitOptions.RemoveEmptyEntries);
}
/// <summary>
/// 获取所有节名
/// </summary>
public string[] GetSections()
{
StringBuilder sb = new StringBuilder(32768);
GetPrivateProfileString(null, null, null, sb, sb.Capacity, filePath);
return sb.ToString().TrimEnd('\0').Split('\0', StringSplitOptions.RemoveEmptyEntries);
}
}使用示例：
// 创建操作对象（文件不存在时会自动创建）
IniHelper ini = new IniHelper(@"C:\Config\app.ini");
// 写入配置
ini.WriteString("Database", "Server", "192.168.1.100");
ini.WriteInt("Database", "Port", 3306);
ini.WriteBool("Logging", "Enabled", true);
// 读取配置
string server = ini.ReadString("Database", "Server", "localhost");
int port = ini.ReadInt("Database", "Port", 3306);
bool loggingEnabled = ini.ReadBool("Logging", "Enabled", false);
Console.WriteLine($"Server: {server}, Port: {port}, Logging: {loggingEnabled}");
// 删除某个键
ini.DeleteKey("Database", "Port");
// 删除整个节
ini.DeleteSection("Logging");方案二：完全托管代码解析（跨平台、无文件大小限制）
如果需要在 Linux/macOS 下运行，或者 INI 文件较大，可以自行实现解析器。
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Text.RegularExpressions;
public class IniFile
{
private Dictionary<string, Dictionary<string, string>> data = new Dictionary<string, Dictionary<string, string>>(StringComparer.OrdinalIgnoreCase);
private string filePath;
public IniFile(string path)
{
filePath = path;
if (File.Exists(path))
Load();
else
data[""] = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
}
private void Load()
{
string currentSection = "";
foreach (string line in File.ReadAllLines(filePath, Encoding.UTF8))
{
string trimLine = line.Trim();
if (string.IsNullOrEmpty(trimLine) || trimLine.StartsWith(";") || trimLine.StartsWith("#"))
continue;
if (trimLine.StartsWith("[") && trimLine.EndsWith("]"))
{
currentSection = trimLine.Substring(1, trimLine.Length - 2);
if (!data.ContainsKey(currentSection))
data[currentSection] = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
}
else
{
int eqIndex = trimLine.IndexOf('=');
if (eqIndex > 0)
{
string key = trimLine.Substring(0, eqIndex).Trim();
string value = eqIndex + 1 < trimLine.Length ? trimLine.Substring(eqIndex + 1).Trim() : "";
if (value.StartsWith("\"") && value.EndsWith("\""))
value = value.Substring(1, value.Length - 2);
if (!data.ContainsKey(currentSection))
data[currentSection] = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
data[currentSection][key] = value;
}
}
}
}
public void Save()
{
using (StreamWriter sw = new StreamWriter(filePath, false, Encoding.UTF8))
{
foreach (var section in data)
{
if (!string.IsNullOrEmpty(section.Key))
sw.WriteLine($"[{section.Key}]");
foreach (var kv in section.Value)
sw.WriteLine($"{kv.Key}={kv.Value}");
if (section.Key != "")
sw.WriteLine();
}
}
}
public string ReadString(string section, string key, string defaultValue = "")
{
if (data.TryGetValue(section, out var keys) && keys.TryGetValue(key, out string value))
return value;
return defaultValue;
}
public void WriteString(string section, string key, string value)
{
if (!data.ContainsKey(section))
data[section] = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
data[section][key] = value;
Save();
}
public int ReadInt(string section, string key, int defaultValue = 0)
{
string str = ReadString(section, key);
return int.TryParse(str, out int val) ? val : defaultValue;
}
public void WriteInt(string section, string key, int value) => WriteString(section, key, value.ToString());
public bool ReadBool(string section, string key, bool defaultValue = false)
{
string str = ReadString(section, key);
if (bool.TryParse(str, out bool b)) return b;
return str == "1" || str == "yes" || str == "true";
}
public void WriteBool(string section, string key, bool value) => WriteString(section, key, value.ToString());
}使用方式：
var ini = new IniFile("config.ini");
ini.WriteString("Network", "IP", "192.168.0.1");
Console.WriteLine(ini.ReadString("Network", "IP"));方案三：使用第三方库 Nini（成熟稳定）
Nini 是一个轻量级的 .NET 配置库，支持 INI、XML、注册表等多种后端。
安装 NuGet 包：
Install-Package Nini
示例代码：
using Nini.Config;
// 加载 INI 文件
IConfigSource source = new IniConfigSource("app.ini");
// 读取配置
string server = source.Configs["Database"].Get("Server");
int port = source.Configs["Database"].GetInt("Port", 3306);
// 修改配置
source.Configs["Database"].Set("Server", "new-server");
source.Save(); // 保存到文件常见问题与注意事项
| 问题 | 解决方案 |
|---|---|
| Windows API 读取中文乱码 | 使用 CharSet = CharSet.Unicode（上面的代码已修正） |
| 文件路径必须是绝对路径 | 调用 Path.GetFullPath(relativePath) 转换 |
| API 读取时最大缓冲区 64KB | 如果节内容极大，改用托管解析方案 |
键或值包含 = 字符 | 托管解析需正确处理，Windows API 会自动处理 |
| 跨平台需求 | 不能使用 kernel32，必须用托管解析或 Nini |
| 注释保留问题 | Windows API 会自动保留注释和空行；托管解析示例不会保留，如需保留可实现更复杂的解析器 |
八、总结
INI 文件操作看似简单，实则涉及编码理论、并发控制、对象映射等深层技术。在 C# 中，平衡原生 API 的便利性与托管方案的灵活性是关键。对于新项目，建议封装 INI 功能为配置提供程序（Configuration Provider），纳入 .NET 统一配置体系，既能保留 INI 的简洁性，又能享受现代配置管理的强类型、变更通知、环境覆盖等高级特性。技术选型上，没有过时的格式，只有不适用的场景——理解业务需求，选择最契合的工具，方为工程智慧。
到此这篇关于C#读写INI配置文件的技术方案与实践指南的文章就介绍到这了,更多相关C#读写INI文件内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！