Apq.Cfg/docs/site/guide/basic-usage.md

基础用法

本页详细介绍 Apq.Cfg 的基础用法。

配置构建器

CfgBuilder 是创建配置的入口点：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .Build();

链式调用

支持链式调用添加多个配置源：

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)
    .AddJson("config.local.json", level: 1, writeable: true, optional: true)
    .AddEnvironmentVariables(level: 2, prefix: "APP_")
    .Build();

配置源优先级

使用 level 参数控制优先级，数值越大优先级越高：

// config.json: { "Key": "value1" }
// config.local.json: { "Key": "value2" }

var cfg = new CfgBuilder()
    .AddJson("config.json", level: 0, writeable: false)        // 优先级低
    .AddJson("config.local.json", level: 1, writeable: true)   // 优先级高
    .Build();

Console.WriteLine(cfg.Get("Key")); // 输出: value2

读取配置值

Get 方法

使用冒号 : 分隔的键路径：

// JSON: { "Database": { "Host": "localhost" } }
var host = cfg.Get("Database:Host");

泛型 Get 方法

获取类型化的值：

// 基本类型
var port = cfg.Get<int>("Database:Port");
var enabled = cfg.Get<bool>("Feature:Enabled");
var ratio = cfg.Get<double>("Settings:Ratio");

// 可空类型
var maxSize = cfg.Get<int?>("Cache:MaxSize");

扩展方法

// 带默认值
var timeout = cfg.GetOrDefault<int>("Database:Timeout", defaultValue: 30);

// 必需的配置（不存在时抛出异常）
var connectionString = cfg.GetRequired<string>("Database:ConnectionString");

// 尝试获取
if (cfg.TryGet<int>("Database:Port", out var port))
{
    Console.WriteLine($"端口: {port}");
}

支持的类型转换

类型	示例
string	"hello"
int, long	123, -456
float, double, decimal	3.14, -2.5
bool	true, false, 1, 0
DateTime	"2024-01-01", "2024-01-01T12:00:00"
TimeSpan	"00:30:00", "1.02:03:04"
Guid	"550e8400-e29b-41d4-a716-446655440000"
Enum	"Warning", 2
Uri	"https://example.com"

配置节

GetSection 方法

获取配置的子节：

var dbSection = cfg.GetSection("Database");

// 读取子节的值
var host = dbSection.Get("Host");
var port = dbSection.Get<int>("Port");

嵌套配置节

// JSON: { "Services": { "Api": { "Url": "..." } } }
var apiSection = cfg.GetSection("Services:Api");
var url = apiSection.Get("Url");

// 或者直接访问
var url = cfg.Get("Services:Api:Url");

配置节属性

var dbSection = cfg.GetSection("Database");

// 获取节的路径
Console.WriteLine(dbSection.Path); // 输出: Database

// 检查键是否存在
if (dbSection.Exists("ConnectionString"))
{
    // 配置存在
}

检查配置存在

// 检查键是否存在
if (cfg.Exists("OptionalFeature:Enabled"))
{
    // 配置存在
}

// 检查值是否为空
var value = cfg.Get("SomeKey");
if (!string.IsNullOrEmpty(value))
{
    // 值存在且不为空
}

获取所有子键

// 获取顶级键
foreach (var key in cfg.GetChildKeys())
{
    Console.WriteLine($"顶级键: {key}");
}

// 获取配置节的子键
var dbSection = cfg.GetSection("Database");
foreach (var key in dbSection.GetChildKeys())
{
    Console.WriteLine($"{key} = {dbSection.Get(key)}");
}

批量操作

批量获取（返回字典）

var keys = new[] { "Database:Host", "Database:Port", "Database:Name" };
var values = cfg.GetMany(keys);

foreach (var (key, value) in values)
{
    Console.WriteLine($"{key} = {value}");
}

批量获取（回调方式，零堆分配）

cfg.GetMany(new[] { "Database:Host", "Database:Port" }, (key, value) =>
{
    Console.WriteLine($"{key} = {value}");
});

批量设置

cfg.SetMany(new Dictionary<string, string?>
{
    ["Database:Host"] = "newhost",
    ["Database:Port"] = "5433"
});

await cfg.SaveAsync();

写入配置

设置单个值

cfg.Set("Database:Timeout", "60");
await cfg.SaveAsync();

移除配置

cfg.Remove("Database:OldSetting");
await cfg.SaveAsync();

指定目标层级

// 写入到特定层级
cfg.Set("Database:Timeout", "60", targetLevel: 1);
await cfg.SaveAsync(targetLevel: 1);

下一步

• 配置合并 - 多配置源合并策略
• 动态重载 - 配置热更新
• 依赖注入 - DI 集成