如何使用 Dapper 连接 SQL Server，并配置和管理连接？

2026-11-04数据小许

Dapper 的数据库连接由 ADO.NET 提供

使用 Dapper 连接 SQL Server 时，通常先通过 SQL Server 的 ADO.NET 驱动创建 SqlConnection，再调用 Dapper 的查询或执行方法。

Dapper 不提供独立的连接类型和连接字符串配置。连接的创建、认证、打开和关闭，以及连接池和事务，主要由驱动负责。Dapper 负责执行 SQL，并将查询结果映射为 .NET 对象。查找完整的连接方法和配置项时，需要同时参考 Dapper 和对应驱动的文档。

应该使用哪种连接类型？

连接 SQL Server 时，常见的连接类有两个：

类型	所属包或命名空间	使用场景
`Microsoft.Data.SqlClient.SqlConnection`	`Microsoft.Data.SqlClient`	新项目通常采用的 SQL Server 驱动连接类型
`System.Data.SqlClient.SqlConnection`	`System.Data.SqlClient`	既有项目中常见，是否继续使用应结合目标框架和项目依赖判断

两者名称相似，但属于不同的驱动，不要在示例中混用命名空间。下面统一使用 Microsoft.Data.SqlClient。

IDbConnection 和 DbConnection 分别是 ADO.NET 的接口和基类，用来表达通用的数据库连接能力。实际连接 SQL Server 时，仍需创建具体的 SqlConnection。

同步和异步的区别在于调用方式，Windows 身份验证与 SQL Server 身份验证的区别在于连接配置。

最小连接示例

先安装依赖：

dotnet add package Dapper
dotnet add package Microsoft.Data.SqlClient

下面采用支持顶级语句的 C# 项目写法，从环境变量读取连接字符串，查询当前数据库名称，无需预先创建业务表：

using System;
using Dapper;
using Microsoft.Data.SqlClient;

var connectionString = Environment.GetEnvironmentVariable(
    "SQLSERVER_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "SQLSERVER_CONNECTION_STRING is not configured.");

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

var databaseName = await connection.QuerySingleAsync<string>(
    "SELECT DB_NAME();");

Console.WriteLine(databaseName);

其中，new SqlConnection(...) 创建连接对象，OpenAsync() 建立数据库连接，QuerySingleAsync<T>() 是 Dapper 提供的扩展方法。离开作用域时，using 会释放连接对象。

连接字符串如何配置？

连接字符串的配置取决于服务器地址、数据库名称、认证方式和部署环境。示例中的占位值需要替换。

使用 Windows 身份验证：

Server=YOUR_SERVER;Database=YOUR_DATABASE;Integrated Security=True;Encrypt=True;TrustServerCertificate=False;

这种配置要求运行程序的身份能够通过数据库服务器的身份验证，并拥有相应权限。跨平台部署还需要满足对应的身份验证条件。

使用 SQL Server 身份验证：

Server=YOUR_SERVER;Database=YOUR_DATABASE;User ID=YOUR_USER;Password=YOUR_PASSWORD;Encrypt=True;TrustServerCertificate=False;

这种配置要求 SQL Server 允许相应的登录方式，并且登录名具有目标数据库的访问权限。密码应通过环境变量、受保护的配置或密钥管理服务提供。

常见配置项包括：

配置项	用途
`Server`	SQL Server 的主机、实例或端口信息
`Database`	要连接的数据库
`Integrated Security`	是否使用集成身份验证
`User ID`、`Password`	SQL Server 身份验证凭据
`Encrypt`	控制连接加密
`TrustServerCertificate`	控制是否绕过服务器证书信任验证
`Connect Timeout`	等待建立连接的超时时间
`Pooling`	控制连接池是否启用

示例要求验证服务器证书，因此服务器证书需要受客户端信任。遇到证书错误时，应检查证书和信任链配置。

连接超时与 SQL 执行超时是不同的配置。Dapper 的执行方法通常通过 commandTimeout 参数指定命令超时，单位为秒。

如何管理连接、查询和事务？

以下是常用 API 及其归属，并非完整列表：

操作	常用 API	归属
打开连接	`Open()`、`OpenAsync()`	`SqlConnection`
关闭连接	`Close()`	`SqlConnection`
释放连接	`Dispose()`、`using`	ADO.NET 连接对象
查看连接状态	`State`	ADO.NET 连接对象
开始事务	`BeginTransaction()`	ADO.NET 连接对象
查询多行	`Query<T>()`、`QueryAsync<T>()`	Dapper
查询恰好一行	`QuerySingle<T>()`、`QuerySingleAsync<T>()`	Dapper
执行非查询 SQL	`Execute()`、`ExecuteAsync()`	Dapper

一般在一次数据库操作或一个事务的范围内创建和释放连接。启用连接池时，关闭或释放连接通常会将底层连接归还连接池，因此不必为了复用而长期保存全局连接对象。

如果一组命令必须处于同一个事务中，应使用同一个连接创建事务，并把事务对象传给每次 Dapper 调用的 transaction 参数。全部操作成功后提交，失败时回滚。

查询参数应通过参数对象传递，例如 new { Id = id }，避免将外部输入直接拼接进 SQL。

完整参考资料应该查什么？

可以根据需要查阅以下文档：

Dapper 官方仓库的 README：查询、参数、结果映射、多结果集等使用示例。
Microsoft Learn 的 Microsoft.Data.SqlClient.SqlConnection API 文档：连接对象的完整方法、属性和事件。
Microsoft Learn 的 SqlConnectionStringBuilder API 文档：连接字符串配置项及其含义。
Microsoft 的 SQL Server ADO.NET 连接池与本地事务文档：连接复用、事务提交和回滚的行为。

阅读驱动文档时，应选择与项目实际使用的包和版本相符的内容。连接字符串默认值、认证能力和框架支持可能存在差异，不能把某个版本的示例直接当成所有环境的配置要求。