SqlSugar 完整使用教程（.NET Framework /.NET Core/.NET 5~10 通用）
SqlSugar 完整使用教程（.NET Framework / .NET Core/.NET 5~10 通用）
一、安装 NuGet
1. 核心包（必装）
Install-Package SqlSugar
2. 对应数据库驱动（按需选一个）
- SQL Server：
Microsoft.Data.SqlClient - MySQL：
MySqlConnector - SQLite：
Microsoft.Data.Sqlite - PostgreSQL：
Npgsql
二、全局配置（推荐封装工具类，项目直接复制）
1. 通用 SqlSugarHelper 工具类
using SqlSugar;
using System;
namespace Demo
{
public static class SqlSugarHelper
{
// 静态全局实例
private static readonly SqlSugarScope _db;
static SqlSugarHelper()
{
// 数据库连接串，根据自己库修改
string connStr = "Server=.;Database=TestDB;Uid=sa;Pwd=123456;TrustServerCertificate=True";
_db = new SqlSugarScope(new ConnectionConfig()
{
ConnectionString = connStr,
DbType = DbType.SqlServer, // 切换库：DbType.MySql / SQLite / PostgreSQL
IsAutoCloseConnection = true, // 自动释放连接
MoreSettings = new ConnMoreSettings()
{
IsWithNoLockQuery = true // 查询加nolock，提升并发
}
},
db =>
{
// 全局过滤器、日志、实体配置统一写这里
db.Aop.OnLogExecuting = (sql, pars) =>
{
// 打印执行SQL，调试用
Console.WriteLine("执行SQL：" + sql);
};
});
}
/// <summary>
/// 获取数据库上下文
/// </summary>
public static SqlSugarScope Db => _db;
}
}
三、实体类示例（表 UserInfo）
using SqlSugar;
namespace Demo.Entity
{
[SugarTable("UserInfo")] // 映射数据库表名
public class UserInfo
{
/// <summary>
/// 主键自增
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public long Id { get; set; }
/// <summary>
/// 用户名
/// </summary>
public string UserName { get; set; }
/// <summary>
/// 年龄
/// </summary>
public int Age { get; set; }
/// <summary>
/// 创建时间，默认当前时间
/// </summary>
public DateTime CreateTime { get; set; }
}
}
四、CRUD 完整示例（LINQ 风格，和LINQ to SQL高度相似）
using Demo;
using Demo.Entity;
using System;
using System.Collections.Generic;
using System.Linq;
namespace Demo.Test
{
public class SqlSugarDemo
{
private readonly ISqlSugarClient _db = SqlSugarHelper.Db;
public void TestAll()
{
// 1. 新增单条
AddOne();
// 2. 批量新增
AddBatch();
// 3. 查询（LINQ写法）
QueryData();
// 4. 修改
UpdateData();
// 5. 删除
DeleteData();
// 6. 分页查询
QueryPage();
// 7. 联表查询
JoinQuery();
// 8. 原生SQL执行
ExecSql();
}
#region 新增
void AddOne()
{
var user = new UserInfo()
{
UserName = "张三",
Age = 22,
CreateTime = DateTime.Now
};
// 返回自增主键
long newId = _db.Insertable(user).ExecuteReturnBigIdentity();
Console.WriteLine("新增ID：" + newId);
}
void AddBatch()
{
List<UserInfo> list = new List<UserInfo>()
{
new UserInfo{UserName="李四",Age=25,CreateTime=DateTime.Now},
new UserInfo{UserName="王五",Age=28,CreateTime=DateTime.Now}
};
// 批量插入
_db.Insertable(list).ExecuteCommand();
}
#endregion
#region 查询
void QueryData()
{
// 1. 查询所有
List<UserInfo> all = _db.Queryable<UserInfo>().ToList();
// 2. 条件查询 LINQ 写法
List<UserInfo> list = _db.Queryable<UserInfo>()
.Where(u => u.Age > 20 && u.UserName.Contains("张"))
.OrderBy(u => u.CreateTime, OrderByType.Desc)
.ToList();
// 3. 查单条
UserInfo single = _db.Queryable<UserInfo>()
.Where(u => u.Id == 1)
.First();
// 4. 只查指定字段（DTO投影）
var dtoList = _db.Queryable<UserInfo>()
.Select(u => new { u.Id, u.UserName })
.ToList();
// 5. 判断是否存在
bool exists = _db.Queryable<UserInfo>().Any(u => u.Id == 1);
}
void QueryPage()
{
// 分页：页码1，每页10条
int pageIndex = 1;
int pageSize = 10;
var pageResult = _db.Queryable<UserInfo>()
.Where(u => u.Age > 18)
.ToPageList(pageIndex, pageSize, out long totalCount);
Console.WriteLine($"总条数：{totalCount}");
}
#endregion
#region 修改
void UpdateData()
{
// 方式1：实体更新（按主键更新）
var user = _db.Queryable<UserInfo>().First(u => u.Id == 1);
user.Age = 30;
_db.Updateable(user).ExecuteCommand();
// 方式2：条件批量更新，只更新指定字段
_db.Updateable<UserInfo>()
.SetColumns(u => u.Age == 35)
.Where(u => u.UserName == "李四")
.ExecuteCommand();
}
#endregion
#region 删除
void DeleteData()
{
// 根据主键删除
_db.Deleteable<UserInfo>().In(1).ExecuteCommand();
// 条件批量删除
_db.Deleteable<UserInfo>().Where(u => u.Age < 18).ExecuteCommand();
}
#endregion
#region 联表查询
void JoinQuery()
{
// UserInfo 关联 Order 示例
var joinList = _db.Queryable<UserInfo, Order>((u, o) => u.Id == o.UserId)
.Select((u, o) => new
{
u.UserName,
o.OrderNo,
o.Amount
})
.ToList();
}
#endregion
#region 原生SQL
void ExecSql()
{
// 查询返回实体
string sql = "select * from UserInfo where Age > @age";
var list = _db.Ado.SqlQuery<UserInfo>(sql, new { age = 20 });
// 执行增删改SQL
string updateSql = "update UserInfo set Age=@age where Id=@id";
_db.Ado.ExecuteCommand(updateSql, new { age = 22, id = 2 });
}
#endregion
}
// 订单实体，联表演示用
[SugarTable("Order")]
public class Order
{
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
public long Id { get; set; }
public long UserId { get; set; }
public string OrderNo { get; set; }
public decimal Amount { get; set; }
}
}
五、事务示例
void TestTran()
{
var db = SqlSugarHelper.Db;
try
{
db.BeginTran();
// 新增用户
long uid = db.Insertable(new UserInfo { UserName = "小明", Age = 20 }).ExecuteReturnBigIdentity();
// 新增订单
db.Insertable(new Order { UserId = uid, OrderNo = "ORD001", Amount = 99 }).ExecuteCommand();
db.CommitTran();
Console.WriteLine("事务成功");
}
catch (Exception ex)
{
db.RollbackTran();
Console.WriteLine("事务回滚：" + ex.Message);
}
}
六、自动建表（CodeFirst，不用手动写SQL建表）
// 不存在则自动创建 UserInfo 表
SqlSugarHelper.Db.DbMaintenance.CreateTableByEntity<UserInfo>();
// 批量创建多个表
var tables = new Type[] { typeof(UserInfo), typeof(Order) };
SqlSugarHelper.Db.DbMaintenance.CreateTableByEntity(tables);
七、优势对比 LINQ to SQL / EF Core
- 上手简单：LINQ 语法和 LINQ to SQL 几乎一致，老项目迁移成本极低；
- 轻量无冗余，内置分表分库、批量操作、软删除、租户过滤；
- 多数据库无缝切换，只需修改
DbType和连接字符串； - 同时支持 LINQ 表达式 + 原生 SQL，灵活兼顾性能与开发效率；
- 国内文档丰富，政企、WinForm、WebApi 大量项目在用。
八、项目使用建议
- 封装
SqlSugarHelper全局静态实例，避免重复创建连接； - 实体统一放在
Entity文件夹，用[SugarTable]标记表； - 简单查询用 LINQ，复杂统计报表混用原生Ado.SqlQuery；
- 批量操作优先
Insertable(list)，性能远高于循环单条新增； - 高并发场景开启
IsAutoCloseConnection自动回收数据库连接。
需要我给你一份适配 MySQL 的连接串 + DbType 替换代码吗？
浙公网安备 33010602011771号