SQLSugar 是一个高效、易用的 .NET ORM 框架，支持多种数据库（如 SQL Server、MySQL、PostgreSQL 等）。它提供了丰富的功能，包括 CRUD 操作、事务管理、动态表名、多表联查等，开发者可以通过简单的链式操作实现复杂的数据库逻辑。
本文将以完整的示例，详细介绍 SQLSugar 的安装、配置和功能使用，适用于 .NET Framework 和 .NET Core 项目。
一、SQLSugar简介
1. 什么是 SQLSugar？
SQLSugar 是一个轻量级的开源 ORM 框架，专注于以下核心功能：
- 简单易用： 通过链式操作简化常见数据库操作。
- 高性能： 优化底层 SQL 执行效率。
- 多数据库支持： 兼容 SQL Server、MySQL、SQLite、PostgreSQL、Oracle 等。
- 功能全面： 支持事务、动态表名、分页、多表联查等高级特性。
2. 使用场景
SQLSugar 适用于以下场景：
- 中小型项目： 快速开发数据库交互模块。
- 动态表结构管理： 需要动态生成或切换表。
- 性能要求高的场景： 适合对 SQL 性能优化有需求的开发者。
二、SQLSugar 的安装
SQLSugar 提供统一的 NuGet 包，无论是 .NET Framework 还是 .NET Core 项目，都直接使用 SqlSugar。
1. 在 .NET Framework 4.6+ 环境安装 SqlSugar
-
使用 NuGet 包管理器安装
打开 Visual Studio，在项目中右键选择“管理 NuGet 程序包”，搜索 SqlSugar 并安装。
注意事项：确保您的项目使用 .NET Framework 4.6 或更高版本，并在 App.config 或 Web.config 文件中正确配置数据库连接字符串。
-
使用 Package Manager Console 安装
在 Visual Studio 的工具菜单中打开 Package Manager Console，输入以下命令：
Install-Package SqlSugar -
使用 .NET CLI 安装
在命令行中运行：
dotnet add package SqlSugar注意： 即使您使用 .NET CLI 安装，SqlSugar 包也完全兼容 .NET Framework 4.6+ 环境。
2. 在 .NET Core 和 .NET 5/6/7/8/9 环境安装 SqlSugarCore
对于基于 .NET Core 和 .NET 5+（包括 .NET 6/7/8/9）的项目，应安装专门的 SqlSugarCore 包。
-
使用 NuGet 包管理器安装
打开 Visual Studio，在项目中右键选择“管理 NuGet 程序包”，搜索 SqlSugarCore并安装。
-
使用 Package Manager Console 安装
在 Visual Studio 的工具菜单中打开 Package Manager Console，输入以下命令：
Install-Package SqlSugarCore -
使用 .NET CLI 安装
在命令行中运行：
dotnet add package SqlSugarCore注意事项：
- SqlSugarCore 是专门为 .NET Core 和 .NET 5/6/7/8/9 构建的轻量级包。
- 确保项目的运行时环境与目标框架一致。
三、SQLSugar 的基本使用教程
1. 数据库上下文配置
创建数据库上下文类
在 SQLSugar 中，通过 SqlSugarClient 管理与数据库的连接。以下示例展示如何创建一个简单的 DbContext 类：
using SqlSugar;
public class DbContext
{
public SqlSugarClient Db { get; }
public DbContext()
{
Db = new SqlSugarClient(new ConnectionConfig()
{
ConnectionString = "Server=localhost;Database=TestDB;User Id=sa;Password=your_password;",
DbType = DbType.SqlServer, // 数据库类型
IsAutoCloseConnection = true, // 自动关闭连接
InitKeyType = InitKeyType.Attribute // 从实体类的特性初始化表结构
});
// 打印SQL到控制台（仅在调试时使用）
Db.Aop.OnLogExecuting = (sql, pars) =>
{
Console.WriteLine($"SQL: {sql}");
};
}
}
2. 实体类定义
SQLSugar 支持通过特性映射数据库表和字段。以下示例定义了一个简单的用户表实体类：
using SqlSugar;
[SugarTable("Users")] // 指定数据库表名为 "Users"
public class User
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)] // 主键且自增
public int Id { get; set; }
public string Name { get; set; }
public int Age { get; set; }
}
3. 数据库基本操作
以下是使用 SQLSugar 进行增删改查的示例：
插入数据
var db = new DbContext().Db;
// 插入单条记录
var user = new User { Name = "Alice", Age = 25 };
db.Insertable(user).ExecuteCommand();
// 插入多条记录
var users = new List<User>
{
new User { Name = "Bob", Age = 30 },
new User { Name = "Charlie", Age = 28 }
};
db.Insertable(users).ExecuteCommand();
查询数据
// 查询单条记录
var user = db.Queryable<User>().First(u => u.Id == 1);
// 条件查询多条记录
var users = db.Queryable<User>().Where(u => u.Age > 20).ToList();
// 动态条件查询
int ageFilter = 25;
var filteredUsers = db.Queryable<User>()
.WhereIF(ageFilter > 0, u => u.Age > ageFilter)
.ToList();
更新数据
// 更新单条记录
var user = new User { Id = 1, Name = "Alice Updated", Age = 26 };
db.Updateable(user).ExecuteCommand();
// 条件更新
db.Updateable<User>()
.SetColumns(u => u.Age == u.Age + 1)
.Where(u => u.Age < 30)
.ExecuteCommand();
删除数据
// 按主键删除
db.Deleteable<User>().In(1).ExecuteCommand();
// 条件删除
db.Deleteable<User>().Where(u => u.Age > 50).ExecuteCommand();
4. 高级功能
事务管理
SQLSugar 提供了简单的事务管理功能，适合多操作的场景：
var db = new DbContext().Db;
db.Ado.UseTran(() =>
{
db.Insertable(new User { Name = "Transaction Test", Age = 20 }).ExecuteCommand();
db.Updateable<User>().SetColumns(u => u.Age == 30).Where(u => u.Name == "Transaction Test").ExecuteCommand();
});
动态表名
通过 AS 方法可以动态指定表名：
var tableName = "Users_2024";
var users = db.Queryable<User>().AS(tableName).ToList();
分页查询
SQLSugar 提供了便捷的分页查询方法：
int totalCount;
var pagedUsers = db.Queryable<User>()
.OrderBy(u => u.Id)
.ToPageList(1, 10, out totalCount); // 第1页，每页10条
Console.WriteLine($"Total Count: {totalCount}");
四、总结
1. 优点
- 易用性： 链式操作降低了开发复杂度。
- 性能优化： 支持多数据库，底层 SQL 执行效率高。
- 功能齐全： 事务管理、动态表名、多表联查等功能一应俱全。
- 跨平台支持： 兼容 .NET Framework 和 .NET Core。
2. 使用建议
SQLSugar 非常适合以下场景：
- 快速开发： 适用于中小型项目，降低了数据库操作门槛。
- 复杂查询优化： 在需要动态查询或表名动态化的场景下表现出色。
- 多数据库项目： 支持多种主流数据库的无缝切换。
