Table of Contents

Interface ICfgRoot

Namespace
Apq.Cfg
Assembly
Apq.Cfg.dll

配置根接口，提供统一的配置访问和管理功能

public interface ICfgRoot : IDisposable, IAsyncDisposable
Inherited Members
Extension Methods

Properties

ConfigChanges

获取配置变更的可观察序列

IObservable<ConfigChangeEvent> ConfigChanges { get; }

Property Value

IObservable<ConfigChangeEvent>

this[string]

通过索引器获取或设置配置值

string? this[string key] { get; set; }

Parameters

key string

配置键

Property Value

string

配置值，不存在时返回null

Examples

// 读取配置
var name = cfg["App:Name"];

// 写入配置
cfg["App:Name"] = "NewName";

Methods

Exists(string)

检查配置键是否存在

bool Exists(string key)

Parameters

key string

配置键

Returns

bool

存在返回true，否则返回false

GetChildKeys()

获取所有顶级配置键

IEnumerable<string> GetChildKeys()

Returns

IEnumerable<string>

GetMany(IEnumerable<string>)

批量获取多个配置值，减少锁竞争

IReadOnlyDictionary<string, string?> GetMany(IEnumerable<string> keys)

Parameters

keys IEnumerable<string>

要获取的键集合

Returns

IReadOnlyDictionary<string, string>

键值对字典

GetMany(IEnumerable<string>, Action<string, string?>)

高性能批量获取：通过回调方式返回结果，零堆分配

void GetMany(IEnumerable<string> keys, Action<string, string?> onValue)

Parameters

keys IEnumerable<string>

要获取的键集合

onValue Action<string, string>

每个键值对的回调处理函数

Remarks

此方法避免了 Dictionary 分配开销，适合高频调用场景。 回调会按键的顺序依次调用。

GetMany<T>(IEnumerable<string>)

批量获取多个配置值并转换为指定类型

IReadOnlyDictionary<string, T?> GetMany<T>(IEnumerable<string> keys)

Parameters

keys IEnumerable<string>

要获取的键集合

Returns

IReadOnlyDictionary<string, T>

键值对字典

Type Parameters

T

目标类型

GetMany<T>(IEnumerable<string>, Action<string, T?>)

高性能批量获取：通过回调方式返回结果并转换类型，零堆分配

void GetMany<T>(IEnumerable<string> keys, Action<string, T?> onValue)

Parameters

keys IEnumerable<string>

要获取的键集合

onValue Action<string, T>

每个键值对的回调处理函数

Type Parameters

T

目标类型

Remarks

此方法避免了 Dictionary 分配开销，适合高频调用场景。 回调会按键的顺序依次调用。

GetSection(string)

获取配置节

ICfgSection GetSection(string key)

Parameters

key string

节的键名（如 "Database"）

Returns

ICfgSection

配置节对象

GetSource(int, string)

根据层级和名称获取配置源

ICfgSource? GetSource(int level, string name)

Parameters

level int

配置源层级

name string

配置源名称

Returns

ICfgSource

配置源实例，不存在时返回 null

Examples

var source = cfg.GetSource(5, "config.local.json");
if (source != null)
{
    var values = source.GetAllValues();
}

GetSources()

获取所有配置源列表

IReadOnlyList<ICfgSource> GetSources()

Returns

IReadOnlyList<ICfgSource>

配置源列表，按层级升序排列

Examples

var sources = cfg.GetSources();
foreach (var source in sources)
{
    Console.WriteLine($"[{source.Level}] {source.Name} ({source.Type})");
}

GetValue<T>(string)

获取配置值并转换为指定类型

T? GetValue<T>(string key)

Parameters

key string

配置键

Returns

T

转换后的配置值，不存在或转换失败时返回默认值

Type Parameters

T

目标类型

Examples

var port = cfg.GetValue<int>("Server:Port");
var enabled = cfg.GetValue<bool>("Features:NewUI");

Reload()

手动触发配置重载

void Reload()

Remarks

对于 Manual 和 Lazy 策略，此方法会立即检查所有配置源并应用更改。 对于 Automatic 策略，此方法不会产生额外效果，因为配置会自动重载。

Remove(string, int?)

移除配置键

void Remove(string key, int? targetLevel = null)

Parameters

key string

配置键

targetLevel int?

目标层级，为null时从所有层级移除

SaveAsync(int?, CancellationToken)

保存配置更改到持久化存储

Task SaveAsync(int? targetLevel = null, CancellationToken cancellationToken = default)

Parameters

targetLevel int?

目标层级，为null时保存所有可写层级

cancellationToken CancellationToken

取消令牌

Returns

Task

表示异步操作的任务

Examples

await cfg.SaveAsync();
// 或指定特定层级
await cfg.SaveAsync(targetLevel: 1);

SetManyValues(IEnumerable<KeyValuePair<string, string?>>, int?)

批量设置多个配置值，减少锁竞争

void SetManyValues(IEnumerable<KeyValuePair<string, string?>> values, int? targetLevel = null)

Parameters

values IEnumerable<KeyValuePair<string, string>>

要设置的键值对

targetLevel int?

目标层级

SetValue(string, string?, int?)

设置配置值

void SetValue(string key, string? value, int? targetLevel = null)

Parameters

key string

配置键

value string

配置值

targetLevel int?

目标层级，为null时使用可写的最高层级

Examples

cfg.SetValue("Server:Port", "8080");
cfg.SetValue("Features:NewUI", "true");

ToMicrosoftConfiguration()

转换为 Microsoft Configuration（静态快照）

IConfigurationRoot ToMicrosoftConfiguration()

Returns

IConfigurationRoot

ToMicrosoftConfiguration(DynamicReloadOptions?)

转换为支持动态重载的 Microsoft Configuration

IConfigurationRoot ToMicrosoftConfiguration(DynamicReloadOptions? options)

Parameters

options DynamicReloadOptions

动态重载选项，为 null 时使用默认选项

Returns

IConfigurationRoot