Class ServiceCollectionExtensions

Namespace

Apq.Cfg

Assembly

Apq.Cfg.dll

IServiceCollection 扩展方法

public static class ServiceCollectionExtensions

Inheritance

object

ServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AddApqCfg(IServiceCollection, Action<CfgBuilder, IServiceProvider>)

添加 Apq.Cfg 配置服务（支持访问 IServiceProvider）

public static IServiceCollection AddApqCfg(this IServiceCollection services, Action<CfgBuilder, IServiceProvider> configure)

Parameters

services IServiceCollection

服务集合

configure Action<CfgBuilder, IServiceProvider>

配置构建器委托，接收 CfgBuilder 和 IServiceProvider

Returns

IServiceCollection

服务集合，支持链式调用

Examples

// 使用 Data Protection 加密
services.AddDataProtection();
services.AddApqCfg((builder, sp) => builder
    .AddJsonFile("appsettings.json", level: 0, writeable: false)
    .AddDataProtectionEncryption(sp.GetRequiredService<IDataProtectionProvider>())
    .AddSensitiveMasking());

Remarks

此重载允许在配置构建过程中访问已注册的服务， 适用于需要依赖其他服务（如 IDataProtectionProvider）的场景。

AddApqCfg(IServiceCollection, Action<CfgBuilder>)

添加 Apq.Cfg 配置服务

public static IServiceCollection AddApqCfg(this IServiceCollection services, Action<CfgBuilder> configure)

Parameters

services IServiceCollection

服务集合

configure Action<CfgBuilder>

配置构建器委托，用于配置各种配置源

Returns

IServiceCollection

服务集合，支持链式调用

Examples

services.AddApqCfg(cfg => cfg
    .AddJsonFile("config.json", level: 0)
    .AddJsonFile($"config.{environment}.json", level: 1)
    .AddEnvironmentVariables(prefix: "APP_", level: 2));

Remarks

此方法会同时注册 ICfgRoot 和 IConfigurationRoot 服务， 使您可以在应用程序中同时使用 Apq.Cfg 和 Microsoft.Extensions.Configuration 的 API。

AddApqCfg(IServiceCollection, Func<IServiceProvider, ICfgRoot>)

添加 Apq.Cfg 配置服务（使用工厂方法）

public static IServiceCollection AddApqCfg(this IServiceCollection services, Func<IServiceProvider, ICfgRoot> factory)

Parameters

services IServiceCollection

服务集合

factory Func<IServiceProvider, ICfgRoot>

配置根工厂方法，接收服务提供者并返回配置根实例

Returns

IServiceCollection

服务集合，支持链式调用

Examples

services.AddApqCfg(sp => {
    var env = sp.GetRequiredService<IWebHostEnvironment>();
    return new CfgBuilder()
        .AddJsonFile("config.json", level: 0)
        .AddJsonFile($"config.{env.EnvironmentName}.json", level: 1)
        .AddEnvironmentVariables(prefix: "APP_", level: 2)
        .Build();
});

Remarks

使用工厂方法可以访问其他已注册的服务，实现更复杂的配置逻辑。 工厂方法只会在首次请求配置时调用一次。

AddApqCfgWithValidation(IServiceCollection, Action<CfgBuilder>, bool)

添加 Apq.Cfg 配置服务并启用验证

public static IServiceCollection AddApqCfgWithValidation(this IServiceCollection services, Action<CfgBuilder> configure, bool validateOnStartup = true)

Parameters

services IServiceCollection

服务集合

configure Action<CfgBuilder>

配置构建器委托

validateOnStartup bool

是否在启动时验证配置，默认为 true

Returns

IServiceCollection

服务集合，支持链式调用

Examples

services.AddApqCfgWithValidation(cfg => cfg
    .AddJsonFile("config.json", level: 0)
    .AddValidation(v => v
        .Required("Database:ConnectionString")
        .Range("Database:Port", 1, 65535)));

Exceptions

ConfigValidationException

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

AddApqCfg<TOptions>(IServiceCollection, Action<CfgBuilder>, string)

添加 Apq.Cfg 配置服务并绑定强类型配置

public static IServiceCollection AddApqCfg<TOptions>(this IServiceCollection services, Action<CfgBuilder> configure, string sectionKey) where TOptions : class, new()

Parameters

services IServiceCollection

服务集合

configure Action<CfgBuilder>

配置构建器委托，用于配置各种配置源

sectionKey string

配置节键名，用于定位 TOptions 的配置数据

Returns

IServiceCollection

服务集合，支持链式调用

Type Parameters

TOptions

配置选项类型

Examples

// 定义配置选项类
public class DatabaseOptions
{
    public string? ConnectionString { get; set; }
    public int Timeout { get; set; } = 30;
}

// 注册配置服务并绑定强类型配置
services.AddApqCfg<DatabaseOptions>(cfg => cfg
    .AddJsonFile("config.json", level: 0)
    .AddEnvironmentVariables(prefix: "APP_", level: 2),
    "Database");

// 使用配置
var dbOptions = serviceProvider.GetRequiredService<IOptions<DatabaseOptions>>().Value;

Remarks

此方法会注册 ICfgRoot、IConfigurationRoot 和 IOptions<TOptions> 服务。 配置选项类必须有无参构造函数。

AddConfigValidator(IServiceCollection, IConfigValidator)

添加配置验证器到服务集合

public static IServiceCollection AddConfigValidator(this IServiceCollection services, IConfigValidator validator)

Parameters

services IServiceCollection

服务集合

validator IConfigValidator

验证器实例

Returns

IServiceCollection

服务集合，支持链式调用

AddConfigValidator(IServiceCollection, Action<ConfigValidationBuilder>)

添加配置验证器到服务集合

public static IServiceCollection AddConfigValidator(this IServiceCollection services, Action<ConfigValidationBuilder> configure)

Parameters

services IServiceCollection

服务集合

configure Action<ConfigValidationBuilder>

验证规则配置委托

Returns

IServiceCollection

服务集合，支持链式调用

Examples

services.AddApqCfg(cfg => cfg.AddJsonFile("config.json", level: 0));
services.AddConfigValidator(v => v
    .Required("Database:ConnectionString")
    .Range("Database:Port", 1, 65535));

ConfigureApqCfg<TOptions>(IServiceCollection, string)

配置强类型选项（从 ICfgRoot 绑定），支持嵌套对象和集合

public static IServiceCollection ConfigureApqCfg<TOptions>(this IServiceCollection services, string sectionKey) where TOptions : class, new()

Parameters

services IServiceCollection

服务集合

sectionKey string

配置节键名，用于定位 TOptions 的配置数据

Returns

IServiceCollection

服务集合，支持链式调用

Type Parameters

TOptions

配置选项类型

Examples

// 定义配置选项类
public class DatabaseOptions
{
    public string? ConnectionString { get; set; }
    public int Timeout { get; set; } = 30;
    public RetryOptions Retry { get; set; } = new();
}

public class RetryOptions
{
    public int Count { get; set; } = 3;
    public int Delay { get; set; } = 1000;
}

// 注册配置服务
services.AddApqCfg(cfg => cfg
    .AddJsonFile("config.json", level: 0)
    .AddEnvironmentVariables(prefix: "APP_", level: 2));

// 绑定强类型配置
services.ConfigureApqCfg<DatabaseOptions>("Database");

// 使用配置
var dbOptions = serviceProvider.GetRequiredService<IOptions<DatabaseOptions>>().Value;
var retryCount = dbOptions.Retry.Count;

Remarks

此方法会注册 IOptions<TOptions>、IOptionsMonitor<TOptions> 和 IOptionsSnapshot<TOptions> 服务。 配置选项类必须有无参构造函数。 支持嵌套对象和集合类型的自动绑定。

ConfigureApqCfg<TOptions>(IServiceCollection, string, Action<TOptions>)

配置强类型选项并启用配置变更监听

public static IServiceCollection ConfigureApqCfg<TOptions>(this IServiceCollection services, string sectionKey, Action<TOptions> onChange) where TOptions : class, new()

Parameters

services IServiceCollection

服务集合

sectionKey string

配置节键名，用于定位 TOptions 的配置数据

onChange Action<TOptions>

配置变更回调函数，当配置发生变化时调用

Returns

IServiceCollection

服务集合，支持链式调用

Type Parameters

TOptions

配置选项类型

Examples

// 定义配置选项类
public class DatabaseOptions
{
    public string? ConnectionString { get; set; }
    public int Timeout { get; set; } = 30;
}

// 注册配置服务并监听变更
services.ConfigureApqCfg<DatabaseOptions>("Database", options => {
    Console.WriteLine($"数据库连接字符串已更新: {options.ConnectionString}");

    // 执行必要的重新连接逻辑
    ReconnectDatabase(options.ConnectionString);
});

void ReconnectDatabase(string connectionString)
{
    // 实现数据库重新连接逻辑
}

Remarks

此方法会注册 IOptions<TOptions>、IOptionsMonitor<TOptions> 和 IOptionsSnapshot<TOptions> 服务， 同时添加一个配置变更监听器。 变更回调会在配置源发生变化且导致 TOptions 实例更新时触发。 返回的 IDisposable 对象可用于取消监听，但已自动注册到服务容器，会在应用关闭时释放。