Table of Contents

Class CfgBuilder

Namespace
Apq.Cfg
Assembly
Apq.Cfg.dll

配置构建器，用于创建和管理配置源

public sealed class CfgBuilder
Inheritance
CfgBuilder
Inherited Members
Extension Methods

Methods

AddEnvironmentVariables(int, string?, string?)

添加环境变量配置源

public CfgBuilder AddEnvironmentVariables(int level = 400, string? prefix = null, string? name = null)

Parameters

level int

配置层级，数值越大优先级越高，默认为 EnvironmentVariables (20)

prefix string

环境变量前缀，为null时加载所有环境变量

name string

配置源名称，为 null 时自动生成

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json")
    .AddEnvironmentVariables(prefix: "APP_")  // 使用默认层级 20
    .Build();

AddJsonFile(string, int, bool, bool, bool, bool, EncodingOptions?, string?)

添加JSON文件配置源

public CfgBuilder AddJsonFile(string path, int level = 0, bool writeable = false, bool optional = true, bool reloadOnChange = true, bool isPrimaryWriter = false, EncodingOptions? encoding = null, string? name = null)

Parameters

path string

JSON文件路径

level int

配置层级，数值越大优先级越高，默认为 Json (0)

writeable bool

是否可写，默认为false

optional bool

是否为可选文件，默认为true

reloadOnChange bool

文件变更时是否自动重载，默认为true

isPrimaryWriter bool

是否为主要写入器，默认为false

encoding EncodingOptions

编码选项，默认为null

name string

配置源名称，为 null 时使用文件名

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json")  // 使用默认层级 0
    .AddJsonFile("config.local.json", level: 5, writeable: true, isPrimaryWriter: true)
    .Build();

AddReadEncodingMapping(string, Encoding, int)

添加读取编码映射（完整路径）

public CfgBuilder AddReadEncodingMapping(string filePath, Encoding encoding, int priority = 100)

Parameters

filePath string

文件完整路径

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 100）

Returns

CfgBuilder

AddReadEncodingMappingRegex(string, Encoding, int)

添加读取编码映射（正则表达式）

public CfgBuilder AddReadEncodingMappingRegex(string regexPattern, Encoding encoding, int priority = 0)

Parameters

regexPattern string

正则表达式模式

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 0）

Returns

CfgBuilder

AddReadEncodingMappingWildcard(string, Encoding, int)

添加读取编码映射（通配符）

public CfgBuilder AddReadEncodingMappingWildcard(string pattern, Encoding encoding, int priority = 0)

Parameters

pattern string

通配符模式（如 ".json"、"config/.xml"、"**/*.txt"）

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 0）

Returns

CfgBuilder

AddSource(ICfgSource, string?)

添加自定义配置源（供扩展包使用）

public CfgBuilder AddSource(ICfgSource source, string? name = null)

Parameters

source ICfgSource

配置源实例，实现 ICfgSource 接口

name string

配置源名称，为 null 时使用配置源自身的 Name 属性

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

// 添加自定义配置源
var customSource = new CustomCfgSource();
var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddSource(customSource)
    .Build();

AddValidation(Action<ConfigValidationBuilder>)

添加配置验证规则

public CfgBuilder AddValidation(Action<ConfigValidationBuilder> configure)

Parameters

configure Action<ConfigValidationBuilder>

验证规则配置委托

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddValidation(v => v
        .Required("Database:ConnectionString")
        .Range("Database:Port", 1, 65535)
        .Regex("App:Email", @"^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$"))
    .Build();

AddValidator(IConfigValidator)

添加自定义验证器

public CfgBuilder AddValidator(IConfigValidator validator)

Parameters

validator IConfigValidator

验证器实例

Returns

CfgBuilder

配置构建器实例，支持链式调用

AddValueMasker(IValueMasker)

添加值脱敏器（供扩展包使用）

public CfgBuilder AddValueMasker(IValueMasker masker)

Parameters

masker IValueMasker

值脱敏器实例

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddValueMasker(new SensitiveMasker())
    .Build();

AddValueTransformer(IValueTransformer)

添加值转换器（供扩展包使用）

public CfgBuilder AddValueTransformer(IValueTransformer transformer)

Parameters

transformer IValueTransformer

值转换器实例

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddValueTransformer(new EncryptionTransformer(provider))
    .Build();

AddWriteEncodingMapping(string, Encoding, int)

添加写入编码映射（完整路径）

public CfgBuilder AddWriteEncodingMapping(string filePath, Encoding encoding, int priority = 100)

Parameters

filePath string

文件完整路径

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 100）

Returns

CfgBuilder

AddWriteEncodingMappingRegex(string, Encoding, int)

添加写入编码映射（正则表达式）

public CfgBuilder AddWriteEncodingMappingRegex(string regexPattern, Encoding encoding, int priority = 0)

Parameters

regexPattern string

正则表达式模式

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 0）

Returns

CfgBuilder

AddWriteEncodingMappingWildcard(string, Encoding, int)

添加写入编码映射（通配符）

public CfgBuilder AddWriteEncodingMappingWildcard(string pattern, Encoding encoding, int priority = 0)

Parameters

pattern string

通配符模式（如 ".json"、"config/.xml"、"**/*.txt"）

encoding Encoding

编码

priority int

优先级（数值越大优先级越高，默认 0）

Returns

CfgBuilder

Build()

构建配置根实例

public ICfgRoot Build()

Returns

ICfgRoot

BuildAndValidate(bool)

构建配置根实例并验证

public (ICfgRoot Config, ValidationResult Result) BuildAndValidate(bool throwOnError = true)

Parameters

throwOnError bool

验证失败时是否抛出异常，默认为 true

Returns

(ICfgRoot Config, ValidationResult Result)

配置根实例和验证结果的元组

Examples

// 构建并验证，失败时抛出异常
var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddValidation(v => v.Required("Database:ConnectionString"))
    .BuildAndValidate();

// 构建并验证，不抛出异常
var (cfg2, result) = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .AddValidation(v => v.Required("Database:ConnectionString"))
    .BuildAndValidate(throwOnError: false);
if (!result.IsValid)
{
    // 处理验证错误
}

Exceptions

ConfigValidationException

当 throwOnError 为 true 且验证失败时抛出

ConfigureEncodingMapping(Action<EncodingMappingConfig>)

配置编码映射（使用 Action 委托进行更复杂的配置）

public CfgBuilder ConfigureEncodingMapping(Action<EncodingMappingConfig> configure)

Parameters

configure Action<EncodingMappingConfig>

配置委托

Returns

CfgBuilder

ConfigureValueTransformer(Action<ValueTransformerOptions>)

配置值转换选项

public CfgBuilder ConfigureValueTransformer(Action<ValueTransformerOptions> configure)

Parameters

configure Action<ValueTransformerOptions>

配置委托

Returns

CfgBuilder

配置构建器实例，支持链式调用

Examples

var cfg = new CfgBuilder()
    .AddJsonFile("config.json", level: 0)
    .ConfigureValueTransformer(options =>
    {
        options.EncryptedPrefix = "[ENCRYPTED]";
        options.SensitiveKeyPatterns.Add("*ApiSecret*");
    })
    .Build();

WithEncodingConfidenceThreshold(float)

设置编码检测置信度阈值（0.0-1.0）

public CfgBuilder WithEncodingConfidenceThreshold(float threshold)

Parameters

threshold float

置信度阈值，范围 0.0-1.0，默认 0.6

Returns

CfgBuilder

WithEncodingDetectionLogging(Action<EncodingDetectionResult>)

启用编码检测日志

public CfgBuilder WithEncodingDetectionLogging(Action<EncodingDetectionResult> handler)

Parameters

handler Action<EncodingDetectionResult>

日志处理器

Returns

CfgBuilder