Dapper Contrib是什么 Dapper Contrib扩展库使用教程

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

Dapper.Contrib 是 Dapper 官方生态中一个轻量、实用的扩展库，它的核心目标很明确：帮你省掉重复写 CRUD SQL 的麻烦，同时不牺牲 Dapper 原有的高性能和简洁性。它不是全功能 ORM，而是“刚好够用”的增强层——所有操作仍基于原生 SQL 生成，但由库自动推导，你只需专注实体和业务逻辑。

它能做什么：四类基础操作全封装

它把最常用的数据库交互抽象成四个直观方法，全部以扩展方法形式挂载在

IDbConnection

上：

Insert：插入单个或批量对象，自动处理自增主键（如 int ID），返回新生成的主键值；支持 Guid 主键（需标注
[ExplicitKey]
） Get：根据主键查单条记录，例如
conn.Get<user>(123)</user>
，等效于
SELECT * FROM Users WHERE Id = @id
Update：按主键更新整行，只提交被修改的字段（不依赖状态跟踪，靠主键定位） Delete：支持按对象实例、主键值或条件批量删除，比如
conn.Delete<order>(new { Status = "Cancelled" })</order>
（需配合 Dapper.Contrib 4.0+ 或自定义扩展）

怎么快速用起来：三步到位

不需要改架构，也不用学新概念，照着做就能跑通：

装包：执行
dotnet add package Dapper.Contrib
，并确保已引用
Dapper
（通常需同时安装
Dapper
主包） 加命名空间：在代码顶部写
using Dapper.Contrib.Extensions;
标实体：给你的类加上
[Table("Users")]
，主键属性加
[Key]
（自增）或
[ExplicitKey]
（如 Guid），其他字段默认映射同名列

关键细节别踩坑

用得顺的前提是理解几个隐含约定：

主键必须存在且唯一标记——没加
[Key]
或
[ExplicitKey]
，
Get
、
Update
、
Delete
都会报错或行为异常
Insert
时，
[Key]
字段会被跳过（交由数据库生成），而
[ExplicitKey]
字段必须提前赋值不支持跨表关联查询或复杂 LINQ 表达式，它只做单表映射；想分页？得自己拼
OFFSET-FETCH
或用第三方分页辅助类批量操作（如
Insert(IEnumerable<t>)</t>
）性能优于循环单条插入，但底层仍是多语句，不是单条 INSERT … VALUES (…), (…) —— 如需极致批量，建议搭配 Dapper 的
Execute
手写 SQL

基本上就这些。它不替代 Dapper，而是让 Dapper 更顺手。写得少，出错少，读得清。