icfg-section.md 6.9 KB
ICfgSection API
ICfgSection 是配置节接口，表示配置的一个子节。
接口定义
public interface ICfgSection
{
/// <summary>
/// 配置节的完整路径
/// </summary>
string Path { get; }
/// <summary>
/// 获取子配置值
/// </summary>
string? Get(string key);
/// <summary>
/// 获取类型化的子配置值
/// </summary>
T? Get<T>(string key);
/// <summary>
/// 检查配置键是否存在
/// </summary>
bool Exists(string key);
/// <summary>
/// 设置子配置值
/// </summary>
void Set(string key, string? value, int? targetLevel = null);
/// <summary>
/// 移除配置键
/// </summary>
void Remove(string key, int? targetLevel = null);
/// <summary>
/// 获取子配置节
/// </summary>
ICfgSection GetSection(string key);
/// <summary>
/// 获取所有子键
/// </summary>
IEnumerable<string> GetChildKeys();
}
属性
Path
配置节的完整路径。
var dbSection = cfg.GetSection("Database");
Console.WriteLine(dbSection.Path); // 输出: Database
var portSection = dbSection.GetSection("Port");
Console.WriteLine(portSection.Path); // 输出: Database:Port
方法
Get
string? Get(string key)
获取子配置的值。
参数：
key: 子配置键（相对于此节的键名）
返回： 配置值，如果不存在返回 null
示例：
var dbSection = cfg.GetSection("Database");
var host = dbSection.Get("Host"); // 等同于 cfg.Get("Database:Host")
var port = dbSection.Get("Port"); // 等同于 cfg.Get("Database:Port")
Get<T>
T? Get<T>(string key)
获取子配置的类型化值。
参数：
key: 子配置键
返回： 转换后的值，不存在或转换失败时返回默认值
示例：
var dbSection = cfg.GetSection("Database");
var port = dbSection.Get<int>("Port"); // 等同于 cfg.Get<int>("Database:Port")
var timeout = dbSection.Get<int>("Timeout"); // 等同于 cfg.Get<int>("Database:Timeout")
Exists
bool Exists(string key)
检查配置键是否存在。
参数：
key: 子配置键（相对于此节的键名）
返回： 存在返回 true，否则返回 false
示例：
var dbSection = cfg.GetSection("Database");
if (dbSection.Exists("ConnectionString"))
{
var connStr = dbSection.Get("ConnectionString");
// 处理连接字符串
}
if (dbSection.Exists("Password"))
{
// 使用密码
}
else
{
// 使用默认认证
}
Set
void Set(string key, string? value, int? targetLevel = null)
设置子配置值。
参数：
key: 子配置键value: 配置值targetLevel: 目标层级（可选，默认写入可写的最高层级）
示例：
var dbSection = cfg.GetSection("Database");
dbSection.Set("Host", "new-host"); // 等同于 cfg.Set("Database:Host", "new-host")
dbSection.Set("Port", "5433"); // 等同于 cfg.Set("Database:Port", "5433")
Remove
void Remove(string key, int? targetLevel = null)
移除配置键。
参数：
key: 子配置键（相对于此节的键名）targetLevel: 目标层级（可选，为 null 时从所有层级移除）
示例：
var dbSection = cfg.GetSection("Database");
dbSection.Remove("OldSetting"); // 等同于 cfg.Remove("Database:OldSetting")
dbSection.Remove("TempValue", targetLevel: 1); // 只从层级1移除
GetSection
ICfgSection GetSection(string key)
获取子配置节。
参数：
key: 子配置节键
返回： ICfgSection 子配置节
示例：
var servicesSection = cfg.GetSection("Services");
var apiSection = servicesSection.GetSection("Api"); // 等同于 cfg.GetSection("Services:Api")
var url = apiSection.Get("Url");
GetChildKeys
IEnumerable<string> GetChildKeys()
获取所有直接子键。
返回： 子键集合
示例：
var dbSection = cfg.GetSection("Database");
foreach (var key in dbSection.GetChildKeys())
{
Console.WriteLine($"{key} = {dbSection.Get(key)}");
}
// 输出:
// Host = localhost
// Port = 5432
// Database = mydb
使用示例
基本用法
var cfg = new CfgBuilder()
.AddJson("config.json", level: 0, writeable: false)
.Build();
// 获取配置节
var dbSection = cfg.GetSection("Database");
// 读取值
var host = dbSection.Get("Host");
var port = dbSection.Get<int>("Port");
// 检查键是否存在
if (dbSection.Exists("Password"))
{
var password = dbSection.Get("Password");
}
// 遍历子键
foreach (var key in dbSection.GetChildKeys())
{
Console.WriteLine($"{key}: {dbSection.Get(key)}");
}
嵌套配置节
// JSON: { "Services": { "Api": { "Url": "...", "Timeout": 30 } } }
var apiSection = cfg.GetSection("Services:Api");
// 或
var apiSection = cfg.GetSection("Services").GetSection("Api");
var url = apiSection.Get("Url");
var timeout = apiSection.Get<int>("Timeout");
修改配置节
var cfg = new CfgBuilder()
.AddJson("config.json", level: 0, writeable: true, isPrimaryWriter: true)
.Build();
var dbSection = cfg.GetSection("Database");
// 设置值
dbSection.Set("Host", "new-host");
dbSection.Set("Port", "5433");
// 移除旧配置
dbSection.Remove("DeprecatedSetting");
await cfg.SaveAsync();
处理数组配置
// JSON: { "Servers": ["s1", "s2", "s3"] }
var serversSection = cfg.GetSection("Servers");
foreach (var key in serversSection.GetChildKeys())
{
var server = serversSection.Get(key);
Console.WriteLine($"Server {key}: {server}");
}
// 输出:
// Server 0: s1
// Server 1: s2
// Server 2: s3
处理对象数组
// JSON: { "Endpoints": [{ "Name": "api", "Url": "..." }, { "Name": "auth", "Url": "..." }] }
var endpointsSection = cfg.GetSection("Endpoints");
foreach (var key in endpointsSection.GetChildKeys())
{
var endpoint = endpointsSection.GetSection(key);
var name = endpoint.Get("Name");
var url = endpoint.Get("Url");
Console.WriteLine($"Endpoint {name}: {url}");
}
检查配置节是否存在
var optionalSection = cfg.GetSection("Optional");
var childKeys = optionalSection.GetChildKeys().ToList();
if (childKeys.Count > 0 || optionalSection.Exists("Value"))
{
// 配置节存在且有内容
}
条件配置处理
var featureSection = cfg.GetSection("Features");
// 检查功能是否启用
if (featureSection.Exists("NewUI") && featureSection.Get<bool>("NewUI"))
{
// 启用新 UI
}
// 获取可选配置，带默认值
var maxRetries = featureSection.Exists("MaxRetries")
? featureSection.Get<int>("MaxRetries")
: 3;