跳到主要内容
.NET 数据操作:SqlSugar 从入门到实战 | 极客日志
C#
.NET 数据操作:SqlSugar 从入门到实战 SqlSugar 是 .NET 生态中轻量高性能的国产 ORM 框架。介绍其核心优势、环境搭建(NuGet 安装、连接初始化)、基础 CRUD 操作(实体映射、增删改查)、进阶特性(事务、缓存、分表)及与 EF Core/Dapper 的对比。适合中小型项目及快速开发场景。
鲜活 发布于 2026/3/26 更新于 2026/5/8 17 浏览.NET 数据操作:SqlSugar 从入门到实战
在 .NET 生态中,ORM(对象关系映射)框架是连接代码与数据库的核心桥梁,既能简化原生 SQL 的繁琐编写,又能兼顾开发效率与性能优化。提及 .NET ORM,EF Core、Dapper 早已广为人知,但 SqlSugar 作为一款轻量、高性能的国产框架,凭借简洁的 API、全面的功能与极低的学习成本,逐渐成为中小型项目与快速开发场景的优选。
一、初识 SqlSugar:什么是它的核心竞争力?
SqlSugar 是由国内开发者 Sunkaixuan 维护的开源 .NET ORM 框架,专注于'轻量无依赖、高性能、易上手'三大核心目标,支持 .NET Framework 4.6+ 及 .NET Core 2.0+ 全版本,兼容 SQL Server、MySQL、PostgreSQL、SQLite、Oracle 等主流数据库,甚至支持达梦等国产数据库,适配多场景开发需求。
相较于同类框架,它的核心优势尤为突出:
性能出众 :底层优化充分,采用编译缓存、SQL 语句优化等机制,性能接近原生 ADO.NET,远超多数同类 ORM,批量操作性能更是优于 Dapper 等框架。
易用性极强 :API 设计简洁直观,支持链式编程,开发者无需深入钻研复杂配置,就能快速实现数据库操作,学习成本远低于 EF Core。
功能全面且灵活 :兼顾基础 CRUD 与高级特性,支持事务管理、分页查询、多表联查、分表分库、缓存控制、数据库迁移(CodeFirst)等,同时允许开发者直接控制 SQL 生成,兼顾灵活性与便捷性。
轻量无依赖 :核心库体积仅几百 KB,无需额外依赖,可无缝集成到各类 .NET 项目中,无冗余负担。
目前,SqlSugar 在 Github 的 Star 数量仅次于 EF Core 与 Dapper,成为 .NET 生态中极具竞争力的 ORM 框架,尤其适合中小型项目、企业内部管理系统等需要快速落地的场景。
二、环境搭建:3 步完成 SqlSugar 集成
SqlSugar 提供两种核心 NuGet 包,分别适配不同 .NET 框架,安装配置过程极简,全程无需复杂操作。
2.1 选择合适的 NuGet 包
根据项目框架选择对应包,避免版本不兼容问题:
.NET Framework 4.6+ 项目:安装 SqlSugar 包;
.NET Core 2.0+、.NET 5/6/7/8/9 项目:安装 SqlSugarCore 包(推荐,轻量适配跨平台场景);
特定数据库扩展:若使用 MySQL,需额外安装 MySqlConnector 驱动包,其他数据库无需额外安装驱动。
2.2 安装方式
支持两种常用安装方式,按需选择即可:
图形化界面安装:打开 Visual Studio,右键点击项目 → 管理 NuGet 程序包 → 浏览,搜索对应包名,点击'安装';
命令行安装:打开程序包管理器控制台,输入对应命令:
.NET Framework 项目:Install-Package SqlSugar;
.NET Core/.NET 5+ 项目:Install-Package SqlSugarCore;
.NET CLI 安装:dotnet add package SqlSugarCore(适配 .NET Core 及以上版本)。
2.3 初始化数据库连接
SqlSugar 的核心操作都通过 SqlSugarClient(非线程安全)或 SqlSugarScope(线程安全,适合单例/依赖注入)完成,初始化时需配置连接参数。以下是两种常见初始化方式:
方式 1:基础初始化(非 IOC 场景)
using SqlSugar;
var connectionConfig = new ConnectionConfig
{
ConnectionString = ,
DbType = DbType.SqlServer,
IsAutoCloseConnection = ,
InitKeyType = InitKeyType.Attribute
};
db = SqlSugarClient(connectionConfig);
db.Aop.OnLogExecuting = (sql, pars) => {
Console.WriteLine( );
Console.WriteLine( );
};
"Server=localhost;Database=TestDB;User Id=sa;Password=your_password;"
true
var
new
$"执行 SQL:{sql} "
$"参数:{string .Join("," , pars.Select(p => $"{p.ParameterName} ={p.Value} " ))} "
方式 2:IOC 注入(ASP.NET Core 场景) 对于 Web 项目,推荐通过依赖注入全局管理 SqlSugarClient,提升代码可维护性:
var builder = WebApplication.CreateBuilder(args );
builder.Services.AddSingleton<ISqlSugarClient>(sp => {
var connectionConfig = new ConnectionConfig
{
ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection" ),
DbType = DbType.SqlServer,
IsAutoCloseConnection = true ,
InitKeyType = InitKeyType.Attribute
};
return new SqlSugarScope(connectionConfig);
});
var app = builder.Build();
之后在控制器中直接注入 ISqlSugarClient 即可使用,无需重复初始化。
三、核心实战:SqlSugar 基础操作(CRUD) 完成初始化后,先定义实体类与数据库表映射,再通过链式 API 实现基础 CRUD 操作,全程无需编写原生 SQL。
3.1 定义实体类(基于特性映射) 通过 SugarTable(类级别)、SugarColumn(属性级别)特性,实现实体类与数据库表的映射,支持自定义表名、字段名、主键、自增等配置:
using SqlSugar;
[SugarTable("Users" ) ]
public class User
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true) ]
public int Id { get ; set ; }
[SugarColumn(ColumnName = "user_name" , Length = 50, IsNullable = false) ]
public string UserName { get ; set ; }
[SugarColumn(ColumnName = "user_pwd" , Length = 100) ]
public string Password { get ; set ; }
[SugarColumn(DefaultValue = "0" ) ]
public int Age { get ; set ; }
[SugarColumn(ColumnName = "reg_time" , DefaultValue = "GETDATE()" ) ]
public DateTime RegTime { get ; set ; }
[SugarColumn(IsIgnore = true) ]
public string TempData { get ; set ; }
}
可选:通过 CodeFirst 自动创建数据库表,无需手动建表:
db.CodeFirst.InitTables<User>();
3.2 基础 CRUD 操作 SqlSugar 的 CRUD 操作均支持链式调用,语法简洁,可灵活组合条件。
(1)新增操作(Insert)
var user = new User
{
UserName = "Alice" ,
Password = "123456" ,
Age = 25
};
int newId = db.Insertable(user).ExecuteReturnIdentity();
var userList = new List<User>
{
new User { UserName = "Bob" , Password = "654321" , Age = 30 },
new User { UserName = "Charlie" , Password = "abc123" , Age = 28 }
};
int affectedRows = db.Insertable(userList).ExecuteCommand();
(2)查询操作(Query) 支持单条查询、条件查询、分页查询、多表联查等多种场景,同时支持原生 SQL 查询:
var user = db.Queryable<User>().In(1 ).First();
var user = db.Queryable<User>().Where(u => u.UserName == "Alice" ).FirstOrDefault();
var userList = db.Queryable<User>().Where(u => u.Age > 20 ).OrderByDesc(u => u.RegTime).ToList();
int pageIndex = 1 ;
int pageSize = 10 ;
var pageResult = db.Queryable<User>().Where(u => u.Age > 18 ).ToPageList(pageIndex, pageSize, out int totalCount);
var result = db.Queryable<User, Order>((u, o) => u.Id == o.UserId)
.Select((u, o) => new { UserId = u.Id, UserName = u.UserName, OrderId = o.Id, OrderName = o.OrderName })
.ToList();
var sql = "SELECT * FROM Users WHERE Age > @Age" ;
var userList = db.Ado.SqlQuery<User>(sql, new { Age = 20 });
(3)修改操作(Update) 支持全量修改、局部修改、批量修改,可精准控制修改字段:
int affectedRows = db.Updateable<User>()
.SetColumns(u => u.Age == 26 )
.Where(u => u.Id == 1 )
.ExecuteCommand();
var user = db.Queryable<User>().In(1 ).First();
user.UserName = "Alice_Update" ;
affectedRows = db.Updateable(user).ExecuteCommand();
affectedRows = db.Updateable<User>()
.SetColumns(u => u.Password == "new_pwd" )
.Where(u => u.Age > 30 )
.ExecuteCommand();
(4)删除操作(Delete)
int affectedRows = db.Deleteable<User>().In(1 ).ExecuteCommand();
affectedRows = db.Deleteable<User>().Where(u => u.UserName == "Bob" ).ExecuteCommand();
affectedRows = db.Deleteable<User>().In(new List<int > { 2 , 3 }).ExecuteCommand();
四、进阶特性:解锁 SqlSugar 高级能力 除基础操作外,SqlSugar 还提供了诸多实用高级特性,覆盖复杂业务场景需求。
4.1 事务管理 支持手动事务与自动事务,确保多步数据库操作的原子性,需注意:事务操作必须使用同一个 SqlSugarClient 实例:
try
{
db.Ado.BeginTran();
db.Insertable(new User { UserName = "David" , Age = 22 }).ExecuteReturnIdentity();
db.Updateable<User>().SetColumns(u => u.Age == 23 ).Where(u => u.Id == 4 ).ExecuteCommand();
db.Ado.CommitTran();
}
catch (Exception ex)
{
db.Ado.RollbackTran();
Console.WriteLine($"事务执行失败:{ex.Message} " );
}
4.2 缓存控制 内置内存缓存,支持自定义 Redis 缓存,减少数据库查询压力,提升接口性能:
var userList = db.Queryable<User>().WithCache(10 * 60 )
var cacheKey = "user_list_age_20" ;
var userList = db.Queryable<User>().Where(u => u.Age > 20 ).WithCache(10 * 60 , cacheKey).ToList();
db.RemoveCache(cacheKey);
4.3 分表分库 支持水平分表、垂直分表与分库操作,适配大数据量场景,无需修改核心业务代码:
var user = new User { UserName = "Eve" , Age = 24 };
db.Insertable(user).AS("Users_" + DateTime.Now.Year)
.ExecuteReturnIdentity();
五、框架对比:SqlSugar 适合哪些场景? 在 .NET 生态中,EF Core、Dapper、SqlSugar 是最常用的三款 ORM 框架,三者定位不同,适配场景各有侧重,以下是核心维度对比:
对比维度 EF Core Dapper SqlSugar 定位 重量级全功能 ORM,适配 DDD 复杂场景 轻量级,极致性能,需手动写 SQL 中轻量,兼顾易用性与性能 性能 中等,复杂查询性能较差 极高,接近原生 ADO.NET 优秀,批量操作优于 Dapper 易用性 学习曲线陡,配置复杂 需熟悉 SQL,灵活但繁琐 学习成本低,链式 API 简洁 核心优势 生态完善,支持复杂关系映射、数据库迁移 性能极致,轻量无依赖 功能全面,兼顾便捷性与灵活性 适配场景 大型企业级应用、复杂业务系统 对性能极致要求,需灵活控制 SQL 的场景 中小型项目、快速开发、企业内部系统 总结 若项目追求快速落地、无需复杂配置,同时需要兼顾性能与功能全面性,SqlSugar 是最优选择;若需构建 DDD 架构的复杂系统,可选择 EF Core;若对性能有极致要求且愿意手动编写 SQL,Dapper 更合适。
六、总结与注意事项 SqlSugar 作为一款国产 ORM 框架,完美平衡了易用性、性能与功能全面性,无需复杂配置就能快速上手,既能满足基础 CRUD 需求,又能支撑分表分库、事务管理、缓存控制等高级场景,尤其适合中小型 .NET 项目与快速开发场景。
确保 SqlSugarClient 实例的线程安全,Web 项目优先使用 SqlSugarScope 与依赖注入;
事务操作需使用同一个客户端实例,否则事务会失效;
切换数据库时,只需修改 ConnectionConfig 的 DbType 与连接字符串,无需修改业务代码;
调试时可开启 SQL 日志输出,便于排查 SQL 生成问题。
总体而言,SqlSugar 是 .NET 开发者提升数据操作效率的得力工具,兼顾'快开发'与'高性能',值得深入学习与应用。后续可结合官方文档,探索更多高级特性,适配更复杂的业务场景。
相关免费在线工具 Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
Markdown转HTML 将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
HTML转Markdown 将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
JSON 压缩 通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
JSON美化和格式化 将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online