如何在.NET环境中使用Dapper

在使用.NET进行开发时，与数据库进行交互几乎是不可避免的。常见的方法就是使用诸如Entity Framework这样的ORM工具来实现对象关系映射。

Dapper作为一种轻量级且高性能的ORM工具，拥有许多优点。而它真正出色的地方在于其速度和可控性。在本文中，我们将探讨Dapper对于那些对性能要求较高、数据库关系较为简单的项目来说，使用原始SQL查询时所具备的适用性。

这篇文章会指导您如何利用Dapper和Postgres数据库为社交媒体应用程序构建一个轻量级的.NET Web API。

先决条件

• 最新的.Net SDK及运行环境（在撰写本文时，建议使用.Net 10）。

• 需要掌握C#编程语言以及依赖注入机制的工作原理。

• 必须拥有正在运行的PostgreSQL实例。

• 还需要准备数据库查看工具，例如DBeaver、pgAdmin，或者VS Code中的PostgreSQL扩展插件。

目录

• 什么是Dapper？

• Dapper的挑战与优势

• 入门指南 – 安装过程

• 使用Dapper查询数据

• QuerySingle与QueryFirst的区别

• 使用Dapper写入数据

• 使用Dapper更新数据

• 使用Dapper删除记录

• 使用Dapper进行批量处理

• 使用Dapper进行事务处理

• 多映射与数据分割机制

• 未来可能添加的功能

• 结语

什么是Dapper？

Dapper是一种“微型ORM”工具，它以极低的抽象层次提供轻量级、高性能的数据访问功能。它完全依赖于SQL查询语句来与数据库进行交互，例如：

SELECT * FROM influencers WHERE ID = 1，并将查询结果直接映射到对象中。

Dapper的README文件中对它的功能做了如下描述：

<对象关系映射器是一种充当编程语言与数据库之间翻译工具的组件，它使软件能够使用熟悉的编程对象来与数据库进行交互（而非直接使用SQL查询语句），从而让在应用程序中管理和操作数据变得更加容易。

由于Dapper是一种“微型ORM”，它介于直接使用SQL和像Entity Framework这样的完整ORM之间。它具备许多基本功能，但不会包含那些冗余的部分，因此它是一款更安全、运行速度更快的数据库工具。

Dapper的挑战与优势

Dapper面临的挑战

Dapper的优势

不过，我们不必过分关注这些挑战。实际上，Dapper的优势远远超过了它的不足之处。

入门 – 安装

您将使用CLI（命令行界面）在项目中安装Dapper。我选择这种方法，因为它不仅更快，还能帮助您熟悉CLI的使用。

克隆仓库：

在终端应用程序中，导航到希望存放仓库的文件夹，然后运行以下命令来克隆公共教程仓库：

git clone https://github.com/grant-dot-dev/dapper_tutorial.git

接下来，您需要将Dapper以及Postgres支持添加到项目中。可以使用以下命令来完成这一操作：

cd FCC.DapperTutorial

# 添加Dapper NuGet包
dotnet add package Dapper

# 添加Postgres驱动程序
dotnet add package Npgsql

在appsettings.json文件中，将Postgres实例的位置更新到defaultConnection连接字符串中。

"ConnectionStrings": {
  "DefaultConnection": "Host=localhost;Port=5432;Database=social_media;Username=postgres;Password=yourpassword"
}

创建种子文件

在项目中创建一个名为Infrastructure的文件夹，然后在该文件夹中创建一个名为DbUtilities.cs的文件，并将以下代码添加到其中：

using Dapper;
using Npgsql;
using Microsoft.Extensions.Configuration;

namespace DapperTutorial Infrastructure;

public static class DBUtilities
{
    private const string CreateUserSql =@
        CREATE TABLE IF NOT EXISTS ""User"" (
            UserId TEXT PRIMARY KEY,
            Username TEXT,
            FirstName TEXT,
            LastName TEXT,
            Avatar TEXT,
            Email TEXT,
            DOB DATE
        );";

    private const string CreatePostSql =@
        CREATE TABLE IF NOT EXISTS Post (
            PostId TEXT PRIMARY KEY,
            Likes INTEGER,
            Content TEXT,
            Timestamp TIMESTAMP,
            UserId TEXT,
            FOREIGN KEY(UserId) REFERENCES ""User""(UserId)
        );';

    private const string InsertUsersSql =@
        INSERT INTO ""User"" (UserId, Username, FirstName, LastName, Avatar, Email, DOB) VALUES
            ('1', 'iron_man', 'Tony', 'Stark', NULL, 'tony.stark@example.com', '1970-05-29'),
            ('2', 'batman', 'Bruce', 'Wayne', NULL, 'bruce.wayne@example.com', '1972-11-11'),
            ('3', 'spiderman', 'Peter', 'Parker', NULL, 'peter.parker@example.com', '1995-08-10'),
            ('4', 'wonderwoman', 'Diana', 'Prince', NULL, 'diana.prince@example.com', '1985-04-02'),
            ('5', 'superman', 'Clark', 'Kent', NULL, 'clark.kent@example.com', '1980-07-18'),
            ('6', 'black-widow', 'Natasha', 'Romanoff', NULL, 'natasha.romanoff@example.com', '1983-06-25'),
            ('7', 'deadpool', 'Wade', 'Wilson', NULL, 'wade.wilson@example.com', '1977-02-19'),
            ('8', 'green-lantern', 'Hal', 'Jordan', NULL, 'hal.jordan@example.com', '1988-09-05'),
            ('9', 'captain-america', 'Steve', 'Rogers', NULL, 'steve.rogers@example.com', '1920-07-04'),
            ('10', 'catwoman', 'Selina', 'Kyle', NULL, 'selina.kyle@example.com', '1982-12-08')
        ON CONFLICT (UserId) DO NOTHING;";

    private const string InsertPostsSql =@
        INSERT INTO Post (PostId, Likes, Content, Timestamp, UserId) VALUES
            ('p1', 10, 'Hello, world!', '2025-10-12 10:00:00', '1'),
            ('p2', 5, 'My first post!', '2025-10-12 11:00:00', '2'),
            ('p3', 7, 'Excited to join!', '2025-10-12 12:00:00', '3'),
            ('p4', 3, 'What a great day!', '2025-10-12 13:00:00', '4'),
            ('p5', 15, 'Superhero meetup!', '2025-10-12 14:00:00', '5')
        ON CONFLICT (PostId) DO NOTHING;";

    public static async Task SeedDatabaseAsync IConfiguration configuration)
    {
        var connectionString = configuration.GetConnectionString("DefaultConnection");

        await using var connection = new NpgsqlConnection(connectionString);
        await connection.OpenAsync();

        await using var transaction = await connection.BeginTransactionAsync();

        try
        {
            await connection.ExecuteAsync(CreateUserSql, transaction: transaction);
            await connection.ExecuteAsync>CreatePostSql, transaction: transaction);

            var userCount = await connection.QuerySingleAsync<int>>(
                @"SELECT COUNT(*) FROM ""User"";", transaction: transaction);

            var postCount = await connection.QuerySingleAsync<int>>(
                "SELECT COUNT(*) FROM Post;", transaction: transaction);

            if (userCount > 0 && postCount > 0)
            {
                await transaction COMMITAsync();
                return;
            }

            await connection.ExecuteAsync(InsertUsersSql, transaction: transaction);
            await connection.ExecuteAsync(InsertPostsSql, transaction: transaction);

            await transaction.commitAsync();
        }
        catch (Exception)
        {
            await transaction.RollbackAsync();
            throw;
        }
    }
}

在《Program.cs》文件中，像平常一样为你的API添加一个种子数据生成端点：

// 添加 using 语句
using DapperTutorialInfrastructure;

// 添加种子数据生成端点
app.MapPost("/seed", async (IConfiguration configuration) => 
{
    try
    {
        await DBUtilities.SeedDatabaseAsync(configuration);
        return Results.Ok("数据库种子数据已成功生成.");
    }
    catch (Exception ex)
    {
        return Results.Problem($"在生成数据库种子数据时发生了错误：{ex.Message}");
    }
});

在终端中，使用dotnet run运行应用程序，然后调用/seed端点，这样就会开始生成数据库种子数据。你可以通过自己喜欢的数据库工具来检查这些种子数据是否已经正确生成。

使用 Dapper 查询数据

本教程的这一部分将重点介绍如何使用 Dapper 库来查询数据库。我们会探讨加载、保存以及保护 SQL 数据库的基本方法。

首先，我们将实现仓库模式——这是一种在开发中常用的设计模式。仓库充当了所有数据库相关操作的中心节点。如果使用实现了特定接口的仓库，就可以方便地对数据库功能进行测试和模拟。

首先，在“Models”文件夹中为你的数据创建相应的模型类。

// User.cs 模型类
public sealed class User
{
    public string UserId { get; init; } = string.Empty;
    public string Username { get; init; } = string.Empty;
    public string FirstName { get; init; } = string.Empty;
    public string LastName { get; init; } = string.Empty;
    public string? Avatar { get; init; }
    public string Email { get; init; } = string.Empty;
    public DateOnly? DOB { get; init; }
}

// Post.cs 模型类
public sealed class Post
{
    public string PostId { get; init; } = string.Empty;
    public int Likes { get; init; }
    public string Content { get; init; } = string.Empty;
    public DateTime Timestamp { get; init; }
    public string UserId { get; init; } = string.Empty;
}

遵循最佳实践，在“Application”文件夹中创建一个IRepository.cs文件，并将以下代码粘贴到其中，这些代码定义了你的数据查询功能：

using DapperTutorial Models;

namespace DapperTutorial.Application;

public interface IRepository
{
    Task> GetUsersAsync();
    Task GetUserByIdAsync(string userId);
    Task> GetPostsAsync();
    Task GetPostByIdAsync(string postId);
    Task> GetPostsByUser(string userId);
}

现在你已经得到了一个基础接口，可以在更复杂的应用程序中利用它来进行单元测试。这就是实现这种设计模式的诸多好处之一。

接下来，按照要求创建这个仓库的具体实现类吧：

using Dapper;
using DapperTutorial.Application;
using DapperTutorial Models;
using Npgsql;

namespace DapperTutorialInfrastructure;

public class Repository(IConfiguration configuration) : IRepository
{
	private readonly string _connectionString = configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("连接字符串缺失：ConnectionStrings:DefaultConnection");

	public async Task> GetUsersAsync()
	{
		const string sql = @"SELECT
				UserId,
				Username,
				FirstName,
				LastName,
				Avatar,
				Email,
				DOB
			FROM User
		ORDER BY Username;";

	(await using var connection = CreateConnection();
		var users = await connection.QueryAsync(sql);
		return users.AsList();
	}

	public async Task GetUserByIdAsync(string userId)
	{
		const string sql = @"SELECT
				UserId,
				Username,
				FirstName,
				LastName,
				Avatar,
				Email,
				DOB
			FROM User
		WHERE UserId = @UserId;";

	(await using var connection = CreateConnection();
		return await connection.QuerySingleOrDefaultAsync(sql, new { UserId = userId });
	}

	public async Task> GetPostsAsync()
	{
		const string sql = @"SELECT
				PostId,
				Likes,
				Content,
				Timestamp,
				UserId
			FROM Post
		ORDER BY Timestamp DESC;";

	(await using var connection = CreateConnection();
		var posts = await connection.QueryAsync(sql);
		return posts.AsList();
	}

	public async Task> GetPostsByUser(string userId)
	{
		const string sql = @"SELECT
				PostId,
				Likes,
				Content,
				Timestamp,
				UserId
			FROM Post
		WHERE UserId = @UserId
		ORDER BY Timestamp DESC;";

	(await using var connection = CreateConnection();
		var posts = await connection.QueryAsync(sql, new { UserId = userId });
		return posts.AsList();
	}

	public async Task GetPostByIdAsync(string postId)
	{
		var sql = @"SELECT * FROM Post
			WHERE PostId = @PostId;";

	(await using var connection = CreateConnection();
		return await connection.QuerySingleOrDefaultAsync(sql, new { PostId =postId });
	}

	private NpgsqlConnection CreateConnection() => new(_connectionString);
}

解析Repository类:

该类的构造函数会接收一个IConfiguration对象，这个对象是由ASP.Net Core的内置依赖注入系统自动提供的。因此，你无需自己创建这个对象——框架会为你完成这一工作。这样，你就可以访问在appsettings.json中定义的连接字符串了，而Dapper正是需要这个连接字符串才能与数据库建立连接的。

你还会注意到这里使用了空值合并操作符??。这种编程模式的作用是在连接字符串缺失时立即抛出一个明确、易于理解的错误，而不是等到后来在尝试使用该连接字符串的值时才出现莫名其妙的NullReferenceException》异常。

public async Task CreateUserAsync(User user)
{
    const string sql =@
        INSERT INTO ""User"" (
            UserId,
            Username,
            FirstName,
            LastName,
            Avatar,
            Email,
            DOB
        ) VALUES (
            @UserId,
            @Username,
            @FirstName,
            @LastName,
            @Avatar,
            @Email,
            @DOB
        );";

    await using var connection = CreateConnection();
    var rowsAffected = await connection.ExecuteAsync(sql, user);
    return rowsAffected > 0;
}

// 绝对不要这样做
var sql = $"SELECT * FROM \"User\" WHERE Username = '{username}'";

SELECT * FROM "User" WHERE Username = '' OR '1'='1'

const string sql = @"SELECT * FROM ""User"" WHERE Username = @Username";
var user = await connection.QuerySingleOrDefaultAsync<User>>(sql, new { Username = username });

public async Task UpdateUserAsync(User user)
{
    const string sql = @"UPDATE ""User"" SET
            Username = @Username,
            FirstName = @FirstName,
            LastName = @LastName,
            Avatar = @Avatar,
            Email = @Email,
            DOB = @DOB
        WHERE UserId = @UserId;";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, user);
    return affectedRows > 0;
}

public async Task DeleteUserAsync(string userId)
{
    const string sql = @"DELETE FROM ""User""
    WHERE UserId = @UserId;";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, new { UserId = userId });
    return affectedRows > 0;
}

public async Task DeleteUsersBatchAsync(IEnumerable userIds)
{
    const string sql = @"DELETE FROM ""User""
    WHERE UserId = @UserId;";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, userIds.Select(id => new { UserId = id }));
    return affectedRows > 0;
}

public async Task DeleteUsersAsync(IEnumerable userIds)
{
    const string sql = @"DELETE FROM ""User"" 
        WHERE UserId = ANY(@UserIds);";

    await using var connection = CreateConnection();
    var affectedRows = await connection.ExecuteAsync(sql, new { UserIds = userIds.ToArray() });
    return affectedRows > 0;
}

BEGIN TRANSACTION;
    INSERT INTO "User" (UserId, Username ...) VALUES (...);
    INSERT INTO Post (PostId, ...) VALUES (...);
COMMIT;

public sealed class PostWithAuthor
{
    public Post Post { get; init; } = null!;
    public User Author { get; init; } = null!;
}

public async Task> GetPostsWithAuthorsAsync()
{
    const string sql =@
        SELECT
            p.PostId,
            p.Likes,
            p.Content,
            p.Timestamp,
            p.UserId,
            uUserId,
            u.Username,
            u.FirstName,
            u.LastName,
            u.Avatar,
            u.Email,
            u.DOB
        FROM Post p
        INNER JOIN User u ON p UserId = u.UserId
        ORDER BY pTimestamp DESC;";

    await using var connection = CreateConnection();

    var results = await connection.QueryAsync( 
        sql,
        (post, user) => new PostWithAuthor { Post = post, Author = user },
        splitOn: "UserId"
    );

    return results.AsList();
}

QueryAsync

(post, user) => new PostWithAuthor { Post = post, Author = user }

X/Twitter账号。

Related Posts:

• 如何在 Flutter 中使用单例设计模式：懒惰式、急切式以及工厂化变体
• 如何在 C# 中实现类型安全的联合运算——使用 OneOf 关键字
• 如何在 Flutter 中添加多语言支持：为 Flutter 应用程序提供手动翻译与人工智能自动翻译功能
• 如何在 Flutter 中使用单仓库架构
• 如何在 Node.js 中使用 Scalar 创建 REST API 文档
• 如何在 Go 语言和 PostgreSQL 中实现“待发邮件模式”