Dapper如何与Dapper.SimpleCRUD结合使用 Dapper扩展库教程

来源：这里教程网时间：2026-02-21 17:35:04 作者：

Dapper.SimpleCRUD 是 Dapper 的轻量级扩展，不是替代品，而是“增强包”——它在 Dapper 原生能力基础上，封装了常用 CRUD 操作，省去手写 SQL 和映射逻辑。两者天然兼容，无需冲突配置，关键在于正确初始化和调用顺序。

安装与基础依赖关系

Dapper.SimpleCRUD 会自动拉取 Dapper 作为依赖，所以只需安装它一个包即可：

通过 NuGet 安装：
Install-Package Dapper.SimpleCRUD
项目中引用命名空间：
using Dapper;
和
using Dapper.SimpleCRUD;
不需单独安装 Dapper，但若已手动装过，版本建议保持一致（推荐 ≥2.1.0）

连接初始化必须调用 InitializeSimpleCRUD()

这是最容易忽略却最关键的一步：Dapper.SimpleCRUD 不会自动注册映射规则，必须显式初始化连接对象。

每次新建
SqlConnection
（或其他 IDbConnection）后，在执行任何 SimpleCRUD 方法前，先调用
connection.InitializeSimpleCRUD()
示例： using (var conn = new SqlConnection(cs))
{
  conn.Open();
  conn.InitializeSimpleCRUD(); // ⚠️ 缺少这句会报错或行为异常
  var user = conn.Get(1);
} 该方法仅做一次映射注册（如主键识别、表名推导），不影响性能，也不需重复调用

实体类设计要点（自动映射靠它）

SimpleCRUD 默认按约定匹配数据库结构，不需要写 SQL，但实体类要满足基本规范：

主键字段名默认为
Id
（大小写敏感），类型支持
int
、
long
、
Guid
；如用其他名（如
UserId
），需加
[Key]
属性（来自
System.ComponentModel.DataAnnotations
）表名默认取类名（如
User
→
Users
），若不符，用
[Table("user_info")]
列名默认与属性名一致；若数据库列是
user_name
，而属性叫
UserName
，可用
[Column("user_name")]
不支持复杂导航属性（如
public List<order> Orders { get; set; }</order>
），一对多需手动查或结合原生 Dapper 处理

混合使用场景：SimpleCRUD + 原生 Dapper

SimpleCRUD 覆盖不了所有需求时，可随时切回 Dapper 原生 API，共享同一连接实例：

增删改查用 SimpleCRUD，复杂查询用 Dapper：
conn.Query<user>("SELECT * FROM Users WHERE Age > @age", new { age = 18 })</user>
事务中混用安全可靠：using var tx = conn.BeginTransaction();
conn.Insert(new User { Name = "A" });
conn.Execute("UPDATE Logs SET Status = 'done' WHERE UserId = @id", new { id = 1 }, tx);
tx.Commit(); 注意：SimpleCRUD 的
Insert
等方法默认不参与外部事务，除非你把
SqlTransaction
显式传入（部分重载支持）

基本上就这些。它不复杂，但初始化和命名约定这两处容易忽略，踩坑多集中在“为什么 Get 找不到数据”或“Insert 返回 0”。对齐好实体和表、记得调