Dapper.Contrib 是 Dapper 的轻量扩展库，自动封装 CRUD 操作，支持 Insert、Get、Update、Delete 四类方法，需标注 [Table]、[Key] 等特性，不支持关联查询与复杂 LINQ。

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

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

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

• Insert：插入单个或批量对象，自动处理自增主键（如 int ID），返回新生成的主键值；支持 Guid 主键（需标注 [ExplicitKey]）
• Get：根据主键查单条记录，例如 conn.Get(123)，等效于 SELECT * FROM Users WHERE Id = @id
• Update：按主键更新整行，只提交被修改的字段（不依赖状态跟踪，靠主键定位）
• Delete：支持按对象实例、主键值或条件批量删除，比如 conn.Delete(new { Status = "Cancelled" })（需配合 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)）性能优于循环单条插入，但底层仍是多语句，不是单条 INSERT … VALUES (…), (…) —— 如需极致批量，建议搭配 Dapper 的 Execute 手写 SQL

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

https://www.php.cn/faq/2004697.html