SettingConfig 1.5.0

Azrng.SettingConfig

一个轻量级、高性能的业务配置管理解决方案，为 ASP.NET Core 应用提供可视化配置管理界面。

✨ 特性

• 🚀 零依赖前端 - 完全使用原生 JavaScript 和现代 CSS，无第三方库依赖
• 📱 响应式设计 - 完美支持移动端和桌面端，自适应各种屏幕尺寸
• 🎨 现代化 UI - 采用 Grid 和 Flexbox 布局，简洁美观的用户界面
• 💾 多数据库支持 - 内置 PostgreSQL 支持，可扩展其他数据库
• 🔄 版本控制 - 配置变更历史记录，支持版本回滚
• 🚦 访问控制 - 支持 Basic 认证和自定义授权策略
• 💨 智能缓存 - 内置内存缓存，可扩展分布式缓存
• 📊 可视化界面 - 直观的配置管理 Dashboard，支持搜索、筛选、编辑
• 🔔 业务回调 - 支持配置编辑前/后、删除前/后的业务回调处理

📦 安装

通过 NuGet 安装

dotnet add package SettingConfig

可选：Basic 认证支持

dotnet add package Azrng.SettingConfig.BasicAuthorization

🚀 快速开始

1️⃣ 配置服务

在 Program.cs 中添加配置服务：

using Azrng.SettingConfig;

var builder = WebApplication.CreateBuilder(args);

// 获取数据库连接字符串
var conn = builder.Configuration.GetConnectionString("pgsql");

// 添加 SettingConfig 服务
builder.Services.AddSettingConfig(options =>
{
    // 数据库配置
    options.DbConnectionString = conn;
    options.DbSchema = "sample";  // 数据库 Schema

    // 路由配置
    options.RoutePrefix = "configDashboard";           // Dashboard 路由前缀
    options.ApiRoutePrefix = "/api/configDashboard";   // API 路由前缀

    // 可选：页面个性化
    options.PageTitle = "系统配置管理";
});

var app = builder.Build();

// 配置 Dashboard 中间件
app.UseSettingDashboard();

app.Run();

2️⃣ 访问管理界面

启动项目后，访问默认地址：

https://localhost:5001/configDashboard

3️⃣ 在代码中使用配置

using Azrng.SettingConfig.Service;

public class MyService
{
    private readonly IConfigExternalProvideService _configService;

    public MyService(IConfigExternalProvideService configService)
    {
        _configService = configService;
    }

    public async Task ExampleAsync()
    {
        // 获取配置内容（字符串）
        var content = await _configService.GetConfigContentAsync("my-config-key");

        // 获取配置内容（反序列化对象）
        var settings = await _configService.GetConfigAsync<MySettings>("my-config-key");
    }
}

🔔 业务回调（新功能）

概述

业务回调允许您在配置变更的关键节点插入自定义逻辑，例如：

• 配置变更前的业务校验
• 配置变更后清除应用缓存
• 配置变更后发送通知
• 配置删除后释放资源

使用自定义回调

using Azrng.SettingConfig;
using Azrng.SettingConfig.Interface;
using Azrng.SettingConfig.Dto;

// 1. 实现自定义回调接口
public class MyConnectInterface : IConnectInterface
{
    private readonly ILogger<MyConnectInterface> _logger;
    private readonly IDistributedCache _cache;

    public MyConnectInterface(ILogger<MyConnectInterface> logger, IDistributedCache cache)
    {
        _logger = logger;
        _cache = cache;
    }

    // 编辑/删除前校验
    public async Task<(bool IsOk, string ErrMsg)> ItemValidate(UpdateConfigDetailsRequest request)
    {
        // 自定义校验逻辑
        if (request.Value.Length > 10000)
        {
            return (false, "配置值不能超过 10000 字符");
        }

        // 可以根据 key 进行特定校验
        if (request.ConfigId == 0) // 假设这是删除操作
        {
            var key = await GetConfigKeyAsync(request.ConfigId);
            if (key == "critical.config")
            {
                return (false, "关键配置不允许删除");
            }
        }

        return (true, string.Empty);
    }

    // 编辑成功后回调
    public async Task<(bool IsOk, string ErrMsg)> EditSuccessHandle(string key, string value)
    {
        try
        {
            // 清除应用缓存
            await _cache.RemoveAsync($"app_config_{key}");

            // 发送通知
            _logger.LogInformation($"配置已更新: {key}");

            // 刷新相关配置
            await RefreshConfiguration(key);

            return (true, string.Empty);
        }
        catch (Exception ex)
        {
            return (false, ex.Message);
        }
    }

    // 删除成功后回调
    public async Task<(bool IsOk, string ErrMsg)> DeleteSuccessHandle(string key, string value)
    {
        try
        {
            // 清除应用缓存
            await _cache.RemoveAsync($"app_config_{key}");

            // 记录删除日志
            _logger.LogWarning($"配置已删除: {key}, 原值: {value}");

            return (true, string.Empty);
        }
        catch (Exception ex)
        {
            return (false, ex.Message);
        }
    }

    private async Task<string> GetConfigKeyAsync(int configId)
    {
        // 实现获取配置 key 的逻辑
        return string.Empty;
    }

    private async Task RefreshConfiguration(string key)
    {
        // 实现刷新配置的逻辑
    }
}

// 2. 注册时使用自定义回调
builder.Services.AddSettingConfig<MyConnectInterface>(options =>
{
    options.DbConnectionString = conn;
    options.DbSchema = "sample";
    options.RoutePrefix = "configDashboard";
    options.ApiRoutePrefix = "/api/configDashboard";
});

使用默认回调（无需回调处理）

// 使用默认实现，所有回调都返回成功
builder.Services.AddSettingConfig(options =>
{
    options.DbConnectionString = conn;
    options.DbSchema = "sample";
});

回调触发时机

回调接口定义

public interface IConnectInterface
{
    /// <summary>
    /// 配置项业务校验（编辑/删除前回调）
    /// 返回 (false, "错误信息") 将中断操作
    /// </summary>
    Task<(bool IsOk, string ErrMsg)> ItemValidate(UpdateConfigDetailsRequest request);

    /// <summary>
    /// 应用配置项更新成功后的业务处理
    /// 用于清除缓存、发送通知等
    /// </summary>
    Task<(bool IsOk, string ErrMsg)> EditSuccessHandle(string key, string value);

    /// <summary>
    /// 应用配置项删除成功后的业务处理
    /// 用于清除缓存、释放资源等
    /// </summary>
    Task<(bool IsOk, string ErrMsg)> DeleteSuccessHandle(string key, string value);
}

🔐 访问控制

默认策略

默认情况下，Dashboard 仅允许本地访问（127.0.0.1）。

Basic 认证

安装 Azrng.SettingConfig.BasicAuthorization 包并配置：

using Azrng.SettingConfig.BasicAuthorization;

builder.Services.AddSettingConfig(options =>
{
    options.DbConnectionString = conn;
    options.DbSchema = "sample";
    options.RoutePrefix = "configDashboard";
    options.ApiRoutePrefix = "/api/configDashboard";

    // 配置 Basic 认证
    options.Authorization = new[]
    {
        new BasicAuthAuthorizationFilter(new BasicAuthAuthorizationFilterOptions
        {
            RequireSsl = false,           // 是否要求 HTTPS
            SslRedirect = false,          // 是否自动重定向到 HTTPS
            LoginCaseSensitive = true,    // 用户名是否区分大小写
            Users = new[]
            {
                new BasicAuthAuthorizationUser
                {
                    Login = "admin",
                    PasswordClear = "your-password"  // 生产环境请使用加密密码
                }
            }
        })
    };
});

自定义授权

实现 IDashboardAuthorizationFilter 接口创建自定义授权策略：

public class CustomAuthorizationFilter : IDashboardAuthorizationFilter
{
    public bool Authorize(DashboardFilterContext context)
    {
        // 自定义授权逻辑
        var httpContext = context.HttpContext;
        // 实现你的授权判断
        return true;
    }
}

🎨 个性化配置

页面配置

options.PageTitle = "我的配置中心";        // 页面标题
options.RoutePrefix = "admin/config";     // 路由前缀
options.ApiRoutePrefix = "/api/config";   // API 路由前缀

数据库配置

options.DbConnectionString = connectionString;  // 连接字符串
options.DbSchema = "public";                     // Schema 名称

🔧 扩展开发

自定义数据源

实现 IDataSourceProvider 接口支持其他数据库：

public class CustomDataSourceProvider : IDataSourceProvider
{
    public async Task InitializeAsync()
    {
        // 初始化数据库连接
    }

    public async Task<IEnumerable<ConfigItem>> GetConfigsAsync()
    {
        // 获取配置列表
    }

    // 实现其他接口方法...
}

📝 版本更新记录

1.5.0 (最新) - 🎉 业务回调版本

• 🆕 新功能：业务回调支持
  • ✅ 支持配置编辑/删除前的业务校验 (ItemValidate)
  • ✅ 支持配置编辑成功后的回调处理 (EditSuccessHandle)
  • ✅ 支持配置删除成功后的回调处理 (DeleteSuccessHandle)
  • ✅ 支持配置恢复成功后的回调处理
  • ✅ 支持泛型注册自定义回调接口 (AddSettingConfig<T>)
  • ✅ 提供默认回调实现 (DefaultConnectInterface)
• ✅ 缓存优化：所有配置变更操作（更新、删除、恢复）统一先清除缓存
• ✅ 代码质量：启用可空引用类型，完善 XML 文档注释
• ✅ 错误处理：改进回调异常处理，确保回调失败不影响主流程

1.4.0 - 🎉 重大优化版本

• 🚀 前端优化: 移除所有外部依赖 (jQuery, Bootstrap, Bootstrap Table, Layer.js)
• ✅ 后端优化: 简化代码，提升可维护性
• 🔒 安全增强: 修复所有 XSS 漏洞，添加完整的安全头
• ⚡ 性能提升: 资源大小减少 97%，加载时间减少 75%
• 🚀 重大改进：完全重构前端，移除所有外部依赖
• ✅ 性能优化：资源大小减少 97% (500KB → 15KB)，加载时间减少 75%
• 🔒 安全增强：修复所有 XSS 漏洞，添加完整的安全头
• 🎨 UI 重构：采用现代化设计，响应式布局，更好的用户体验
• 📱 移动端优化：完美支持各种屏幕尺寸
• ✨ 功能增强：改进搜索、分页、复制等功能
• 🛠️ 技术升级：使用原生 JavaScript，现代 CSS (Grid, Flexbox)

1.3.1

• 🆕 新增：支持完全离线使用，所有前端资源本地化
• ✅ 优化：下载并本地化 Bootstrap、jQuery、Bootstrap Table 等依赖资源
• ✅ 优化：添加 Bootstrap Icons 字体文件支持
• ✅ 优化：内网环境无需外部网络连接即可正常使用

1.3.0

• 🆕 新增：支持 .NET 9.0
• ✅ 优化：启用可空引用类型支持
• ✅ 优化：改进包版本管理，使用浮动版本号
• ✅ 优化：完善 DashboardOptions 的 XML 文档注释
• ✅ 重构：移除注释代码，清理构造函数逻辑

1.2.0

• 支持 .NET 10

1.1.0

• 适配 Azrng.Core 1.2.1 的修改

1.0.1

• 支持通过调用 AddIfNotExistsAsync 接口初始化数据

1.0.0

• 增加了历史版本配置的复制
• 增加 Basic 认证方案

0.0.1

• 基本的配置更新