C#Dapper 超全详细使用教程(从入门到进阶)

C# Dapper 超全详细使用教程(从入门到进阶)

Dapper 是一款专为.NET设计的轻量级、高性能ORM(对象关系映射)框架,核心是扩展 ADO.NET 的 IDbConnection 接口,摒弃了复杂的配置和冗余的上下文管理,以极简的API封装原生SQL操作,性能接近手写ADO.NET,同时兼顾开发效率,是.NET项目中高频使用的数据持久化框架。本文将从基础概念、环境搭建、核心原理、基础CRUD、高级功能、最佳规范、优缺点等方面,全方位讲解Dapper的完整使用方案。

一、Dapper 核心基础介绍

1.1 核心原理

Dapper 基于 ADO.NET 底层封装,通过扩展方法增强 IDbConnection 接口能力,核心工作流程简单高效:

  1. 建立数据库连接:依托原生ADO.NET的IDbConnection接口创建数据库连接;

  2. 执行SQL语句:通过Dapper封装的扩展方法执行原生SQL或存储过程;

  3. 自动结果映射:将数据库查询结果集自动映射为C#实体对象或集合。

其高性能的核心原因:无复杂的实体跟踪、无需动态生成SQL、内置SQL查询计划缓存,最大程度减少性能开销。

1.2 Dapper 与主流数据库框架对比

为清晰区分各框架适用场景,以下是Dapper与EF、NHibernate、原生ADO.NET的特性对比:

特性 Dapper Entity Framework NHibernate ADO.NET
性能 极高(接近原生) 中等 中等 极高
易用性 高、API简洁 高、开箱即用 中等、配置繁琐 低、代码冗余
实体映射能力 基础强类型映射 丰富、全自动映射 丰富、全自动映射 无、手动映射
学习曲线 极低 中等 较高 低
事务支持 完整支持 完整支持 完整支持 原生支持
LINQ支持 不支持 全面支持 全面支持 不支持
配置灵活性 极高、完全掌控SQL 中等、封装度高 高、自定义性强 极高

二、环境准备与基础配置

2.1 安装Dapper NuGet包

项目使用Dapper前,必须安装官方NuGet包,提供三种安装方式:

  1. Visual Studio可视化安装:右键项目 → 管理NuGet程序包 → 搜索「Dapper」安装;

  2. 包管理器控制台:Install-Package Dapper;

  3. .NET CLI命令:dotnet add package Dapper。

2.2 引入核心命名空间

以SQL Server为例,需引入以下必备命名空间,其他数据库需替换对应连接命名空间:

using System.Data;                  // 数据库操作核心接口
using System.Data.SqlClient;       // SQL Server连接专属命名空间
using Dapper;                      // Dapper核心扩展命名空间

补充:MySQL对应命名空间为 MySqlConnector,PostgreSQL对应 Npgsql。

2.3 数据库连接配置

Dapper无连接池封装,完全依赖原生IDbConnection,标准使用方式为静态连接字符串+using自动释放连接,避免资源泄露:

// 数据库连接字符串(根据自身数据库配置修改)
private static readonly string _connectionString = 
    "Server=你的服务器名;Database=你的数据库名;Uid=用户名;Pwd=密码;TrustServerCertificate=True;";

// 标准连接使用模板
using (IDbConnection dbConnection = new SqlConnection(_connectionString))
{
    dbConnection.Open(); // 显式打开连接(可控性更强,推荐使用)
    // 所有数据库操作代码写在此代码块中
}

三、Dapper 基础CRUD操作(核心入门)

Dapper核心方法分为两类:Query系列(查询)、Execute(增删改),全程支持参数化查询,杜绝SQL注入。

3.1 定义对应数据库实体类

实体类字段建议与数据库表字段一致,字段不一致时可通过[Column("数据库字段名")] 特性映射:

public class User
{
    public int Id { get; set; }         // 主键ID
    public string UserName { get; set; }// 用户名
    public int Age { get; set; }        // 年龄
    public DateTime CreateTime { get; set; } // 创建时间
}

3.2 查询操作(单条/多条)

3.2.1 查询多条数据

使用 Query<T>() 方法,返回实体集合:

/// <summary>
/// 查询所有用户
/// </summary>
public List<User> GetAllUsers()
{
    using (IDbConnection db = new SqlConnection(_connectionString))
    {
        db.Open();
        string sql = "SELECT Id, UserName, Age, CreateTime FROM Users;";
        // 自动映射为User实体列表
        List<User> userList = db.Query<User>(sql).ToList();
        return userList;
    }
}

3.2.2 查询单条数据

使用 QueryFirstOrDefault<T>() 方法,无数据返回null,支持参数化查询:

/// <summary>
/// 根据ID查询单个用户
/// </summary>
public User GetUserById(int userId)
{
    using (IDbConnection db = new SqlConnection(_connectionString))
    {
        db.Open();
        // @Id为参数占位符,Dapper自动映射匿名对象参数
        string sql = "SELECT Id, UserName, Age, CreateTime FROM Users WHERE Id = @Id;";
        User user = db.QueryFirstOrDefault<User>(sql, new { Id = userId });
        return user;
    }
}

3.3 插入操作

使用 Execute() 方法,返回受影响的数据库行数,支持实体对象自动参数映射:

/// <summary>
/// 新增用户数据
/// </summary>
public int InsertUser(User newUser)
{
    using (IDbConnection db = new SqlConnection(_connectionString))
    {
        db.Open();
        string sql = @"INSERT INTO Users (UserName, Age, CreateTime) 
                       VALUES (@UserName, @Age, @CreateTime);";
        // 直接传入实体对象,自动匹配参数
        int affectedRows = db.Execute(sql, newUser);
        return affectedRows;
    }
}

3.4 更新操作

同样使用 Execute() 方法,根据条件更新数据:

/// <summary>
/// 更新用户信息
/// </summary>
public int UpdateUser(User updateUser)
{
    using (IDbConnection db = new SqlConnection(_connectionString))
    {
        db.Open();
        string sql = @"UPDATE Users 
                       SET UserName = @UserName, Age = @Age 
                       WHERE Id = @Id;";
        int affectedRows = db.Execute(sql, updateUser);
        return affectedRows;
    }
}

3.5 删除操作

通过 Execute() 实现条件删除,支持匿名对象传参:

/// <summary>
/// 根据ID删除用户
/// </summary>
public int DeleteUser(int userId)
{
    using (IDbConnection db = new SqlConnection(_connectionString))
    {
        db.Open();
        string sql = "DELETE FROM Users WHERE Id = @Id;";
        int affectedRows = db.Execute(sql, new { Id = userId });
        return affectedRows;
    }
}

3.6 存储过程调用

Dapper支持直接调用数据库存储过程,只需指定命令类型为存储过程:

using (IDbConnection db = new SqlConnection(_connectionString))
{
    // 调用名为GetStudentById的存储过程,传入参数
    var result = db.Query<User>("GetUserById", 
        new { Id = 1 }, 
        commandType: CommandType.StoredProcedure).FirstOrDefault();
}

四、Dapper 高级进阶功能

除基础CRUD外,Dapper支持多表映射、事务、批量操作、动态查询等复杂场景,满足企业级开发需求。

4.1 多表关联映射(一对一/一对多)

支持多表联查,将多表结果自动映射到嵌套实体,通过 splitOn 指定分割字段:

// 学生实体(嵌套班级实体)
public class Student
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public Class Class { get; set; }
}
// 班级实体
public class Class
{
    public int Id { get; set; }
    public string ClassName { get; set; }
}

// 多表联查映射
string sql = "SELECT * FROM Students s INNER JOIN Classes c ON s.ClassId = c.Id";
var studentDict = new Dictionary<int, Student>();

using (IDbConnection db = new SqlConnection(_connectionString))
{
    var studentList = db.Query<Student, Class, Student>(sql, 
        (student, cls) => 
        {
            student.Class = cls;
            return student;
        }, splitOn: "Id").Distinct().ToList();
}

4.2 事务处理(保证数据一致性)

Dapper完全兼容ADO.NET事务,支持多操作原子执行,要么全部成功,要么全部回滚:

using (IDbConnection db = new SqlConnection(_connectionString))
{
    db.Open();
    // 开启事务
    using (var transaction = db.BeginTransaction())
    {
        try
        {
            // 执行新增
            string insertSql = "INSERT INTO Students (Name, Age) VALUES (@Name, @Age)";
            db.Execute(insertSql, new { Name = "John", Age = 22 }, transaction);

            // 执行更新
            string updateSql = "UPDATE Students SET Age = @Age WHERE Name = @Name";
            db.Execute(updateSql, new { Age = 23, Name = "John" }, transaction);

            // 提交事务
            transaction.Commit();
        }
        catch
        {
            // 异常回滚
            transaction.Rollback();
        }
    }
}

4.3 批量数据操作

Dapper支持直接传入实体集合,一次性完成批量新增/修改,性能高效:

using (IDbConnection db = new SqlConnection(_connectionString))
{
    string sql = "INSERT INTO Students (Name, Age) VALUES (@Name, @Age)";
    // 实体集合批量插入
    var studentList = new List<Student>
    {
        new Student { Name = "John", Age = 22 },
        new Student { Name = "Jane", Age = 24 },
        new Student { Name = "Mark", Age = 26 }
    };
    // 批量执行,无需循环调用
    db.Execute(sql, studentList);
}

4.4 动态对象查询

适用于查询结果结构不固定、无需定义实体类的场景,使用dynamic动态接收数据:

using (IDbConnection db = new SqlConnection(_connectionString))
{
    string sql = "SELECT Name, Age FROM Students";
    // 动态对象接收结果
    var studentList = db.Query<dynamic>(sql).ToList();
    foreach (var student in studentList)
    {
        Console.WriteLine($"姓名:{student.Name},年龄:{student.Age}");
    }
}

4.5 查询缓存优化

Dapper内置查询缓冲机制,开启buffered可缓存查询结果,减少重复数据库请求开销(默认开启):

using (IDbConnection db = new SqlConnection(_connectionString))
{
    string sql = "SELECT * FROM Students";
    // 开启结果缓存,提升重复查询性能
    var studentList = db.Query<Student>(sql, buffered: true).ToList();
}

五、跨数据库适配方案

Dapper 无数据库绑定特性,可无缝适配主流数据库,仅需替换NuGet包、连接对象、连接字符串:

  • MySQL:安装 MySqlConnector 包,使用 MySqlConnection 连接对象;

  • PostgreSQL:安装 Npgsql 包,使用 NpgsqlConnection 连接对象;

  • SQLite:安装 System.Data.SQLite 包,使用 SQLiteConnection 连接对象。

六、核心使用规范与最佳实践

  1. 强制使用参数化查询:所有动态条件必须使用 @参数占位符,杜绝字符串拼接SQL,彻底防止SQL注入;

  2. using托管连接资源:所有IDbConnection对象必须包裹using语句,自动释放数据库连接,避免连接池泄露;

  3. 区分核心方法用途:Query系列方法仅用于查询,Execute方法统一用于增、删、改操作;

  4. 优先显式打开连接:手动调用Open(),相比Dapper自动打开连接,代码可控性更强,便于事务和批量操作;

  5. 规范实体映射:尽量保持实体属性与数据库字段一致,不一致时使用[Column]特性显式映射。

七、Dapper 优缺点总结与适用场景

7.1 核心优势

  • 性能极致:无多余封装,性能接近原生ADO.NET,远超EF等重型框架;

  • 轻量无侵入:体积小、零配置、学习成本极低,快速集成;

  • 灵活性极强:完全掌控原生SQL,支持复杂查询、存储过程、批量操作;

  • 安全性高:原生支持参数化查询,杜绝SQL注入风险;

  • 兼容性好:支持所有主流关系型数据库,支持事务、缓存、多表映射。

7.2 局限性

  • 不支持LINQ查询,需手动编写SQL,复杂查询需自行维护SQL语句;

  • 无实体变化跟踪、级联操作等高级ORM功能;

  • 自动映射能力有限,复杂多对多关系需手动配置映射逻辑。

7.3 适用场景

适合中小型项目、高性能数据接口、老旧项目改造、需要精准控制SQL的场景;不适合超大型复杂业务、依赖全自动ORM映射、需要大量LINQ查询的项目。

八、全文总结

Dapper 以“轻量、高效、灵活”为核心优势,平衡了原生ADO.NET的高性能和传统ORM的易用性。其核心使用逻辑简单:安装NuGet包→配置数据库连接→通过Query/Execute实现CRUD→借助高级功能适配复杂场景。在实际开发中,只要遵循参数化查询、using资源释放等规范,即可高效、稳定地完成各类数据库操作,是.NET生态中不可或缺的数据持久化工具。

posted @ 2026-06-09 15:43  人生就是修炼  阅读(649)  评论(0)    收藏  举报