推荐一款.net SqlSugar ORM 一站式扩展库 RuoVea.ExSugar

🍬 RuoVea.ExSugar

SqlSugar ORM 一站式扩展库 — 集成 DI 注册、DbContext/Repository 模式、审计字段自动填充、全局查询过滤器、工作单元事务、差异日志记录、SM2 连接字符串加密，覆盖从 DataExecuting AOP 到分页查询的完整数据访问层抽象。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：DbContext 模式
  • 场景二：Repository 仓储模式
  • 场景三：审计字段自动填充
  • 场景四：全局查询过滤器
  • 场景五：工作单元事务
  • 场景六：差异日志记录
  • 场景七：连接字符串 SM2 加密
  • 场景八：敏感数据国密加密
• ⚙️ 配置选项详解
• 🏗️ 实体基类体系
• 📐 SQL 扩展方法
• 📄 分页查询
• 🧵 线程安全与生命周期
• ⚠️ 已知问题与注意事项
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExSugar 为 .NET 开发者提供 SqlSugar ORM 的开箱即用增强封装，通过 DI 容器统一管理数据库连接、审计字段、查询过滤器和事务边界。

┌─────────────────────────────────────────────────────────┐
│ RuoVea.ExSugar │
├─────────────────────────────────────────────────────────┤
│ DI 注册 实体基类 仓储模式 │
│ ├─ AddSqlSugarSetup ├─ EntityBase ├─ SugarRepository<T>
│ ├─ AddDbContextSetup ├─ EntityTenant └─ SimpleClient<T>
│ └─ AddInjectServiceSetup├─ AutoKeyBase │
│ └─ AutoKeyEntityBase │
│ │
│ 审计 AOP 全局过滤器 工作单元 │
│ ├─ DataExecuting ├─ 软删除过滤器 ├─ UnitOfWorkAttribute
│ ├─ 创建时间自动填充 ├─ 用户Id过滤器 └─ UnitOfWorkFilter
│ ├─ 修改时间自动填充 ├─ 租户Id过滤器 │
│ ├─ 雪花Id自动生成 └─ moreFilter │
│ └─ 租户Id自动设置 │
│ │
│ 差异日志 连接安全 扩展方法 │
│ ├─ OnDiffLogEvent ├─ SM2 加密解密 ├─ SqlSugarClient
│ ├─ UpdateWithDiffLog └─ IsEncrypt │ 扩展 (40+ 方法)
│ └─ InsertWithDiffLog └─ ISugarQueryable
│ 分页扩展 │
│ │
│ 敏感数据加密 TypeHandler │
│ ├─ SM4-CBC 加解密 ├─ SensitiveDataConverter │
│ └─ SM4-ECB 加解密 └─ ISugarDataConverter │
├─────────────────────────────────────────────────────────┤
│ 国际化: zh-CN │
└─────────────────────────────────────────────────────────┘

设计原则

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExSugar –version 8.0.0.33

# .NET 10.0
dotnet add package RuoVea.ExSugar –version 10.0.0.7

Package Manager

Install-Package RuoVea.ExSugar -Version 8.0.0.33

PackageReference

<PackageReference Include=\”RuoVea.ExSugar\” Version=\”8.0.0.33\” />

框架引用要求

RuoVea.ExSugar 需要 Microsoft.AspNetCore.App 框架引用（自动包含在 ASP.NET Core 项目中）：

<FrameworkReference Include=\”Microsoft.AspNetCore.App\” />

支持的 Target Framework

传递依赖

⚡ 30 秒快速开始

1. 配置 appsettings.json

{
\”ConnectionConfigs\”: [
{
\”ConfigId\”: \”1300000000001\”,
\”DbType\”: \”MySql\”,
\”ConnectionString\”: \”Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;\”,
\”IsAutoCloseConnection\”: true,
\”EnableDiffLog\”: false,
\”EnableUnderLine\”: true,
\”IsEncrypt\”: false,
\”IsDeleteFilter\”: true,
\”IsUserIdFilter\”: false,
\”IsTenantIdFilter\”: false,
\”CommandTimeOut\”: 30
}
],
\”DataAuditing\”: {
\”CreateTime\”: \”CreateTime\”,
\”ModifyTime\”: \”ModifyTime\”,
\”Creator\”: \”Creator\”,
\”Modifier\”: \”Modifier\”,
\”TenantId\”: \”TenantId\”,
\”IsDelete\”: \”IsDelete\”
}
}

💡 提示: DataAuditing 各审计字段默认值即驼峰字段名（TenantId 默认值已修正为 \”TenantId\”），如需映射为下划线等自定义列名再在此覆写。

2. 注册服务

// Program.cs / Startup.cs
using RuoVea.ExSugar;

// <inheritdoc cref=\”SqlSugarSetup.AddSqlSugarSetup(IServiceCollection, bool, ICacheService, ServiceLifetime, Action{SqlSugarScopeProvider})\”/>
// 方式一：从 appsettings.json 自动读取（最简）
builder.Services.AddSqlSugarSetup();

// 方式二：显式传入 IConfiguration
builder.Services.AddSqlSugarSetup(builder.Configuration);

// 方式三：代码构建配置
builder.Services.AddSqlSugarSetup(configs =>
{
configs.Add(new DbConnectionConfig
{
ConfigId = \”1300000000001\”,
DbType = SqlSugar.DbType.MySql,
ConnectionString = \”Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;\”,
EnableUnderLine = true
});
});

3. 使用 SugarRepository

// <inheritdoc cref=\”SugarRepository{T}\”/>
public class UserService
{
private readonly SugarRepository<MyUser> _userRepo;

public UserService(SugarRepository<MyUser> userRepo)
{
_userRepo = userRepo;
}

public async Task<List<MyUser>> GetAllAsync()
{
return await _userRepo.GetListAsync(u => u.IsDelete == IsDelete.N, u => u.Id);
}

public async Task<MyUser?> GetByIdAsync(long id)
{
return await _userRepo.GetFirstAsync(u => u.Id == id, u => u.Id);
}
}

30 秒内你完成了: 配置文件编写 → DI 注册 → 使用泛型仓储查询数据。审计字段自动填充、软删除过滤、连接池管理全部由底层 AOP 接管。

🧩 核心场景

场景一：DbContext 模式

┌──────────────────┐
│ 自定义 DbContext │ 继承 abstract class DbContext
│ (e.g. MyDbCtx) │ 实现 IDbContext, IDisposable
└────────┬─────────┘
│ 注入
▼
┌──────────────────┐
│ services. │ AddDbContextSetup<MyDbCtx>(sp => new MyDbCtx(config))
│ AddDbContextSetup│
└──────────────────┘

// <inheritdoc cref=\”DbContext.DbContext(DbConnectionConfig, int, ICurrentUser, IRestFulLog, bool, bool, bool, Action{SqlSugarScopeProvider})\”/>
/// <summary>
/// 自定义数据库上下文，继承抽象基类 DbContext
/// </summary>
public class MyDbContext : DbContext
{
public MyDbContext(DbConnectionConfig config,
ICurrentUser currentUser = null,
IRestFulLog restFulLog = null)
: base(config, commandTimeOut: 30,
currentUser: currentUser,
restFulLog: restFulLog,
userIdFilter: false,
tenantIdFilter: false,
deleteFilter: true)
{
}

// 使用 db 字段访问 SqlSugarClient
public List<MyUser> GetActiveUsers() =>
db.ToList<MyUser>(u => u.IsDelete == IsDelete.N);
}

// 注册
builder.Services.AddDbContextSetup(sp =>
{
var config = new DbConnectionConfig
{
ConfigId = \”1300000000001\”,
DbType = SqlSugar.DbType.MySql,
ConnectionString = \”Server=127.0.0.1;Database=MyDb;Uid=root;Pwd=123456;\”
};
return new MyDbContext(config,
sp.GetService<ICurrentUser>(),
sp.GetService<IRestFulLog>());
});