Dapper的CommandDefinition结构怎么用 Dapper高级查询构造

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

Dapper 的

CommandDefinition

是一个轻量但关键的结构体，用于显式控制 SQL 执行的全部细节——它不替代直接写 SQL，而是把“怎么查”这件事从方法签名里解耦出来，让高级查询构造更清晰、更可控。

什么时候该用 CommandDefinition 而不是简单传参

当你需要精细调控以下任一行为时，就该跳出

Query<t>(sql, param)</t>

这类快捷方式，改用

CommandDefinition

：

设置非默认超时（比如报表查询设 90 秒，而列表页固定 5 秒） 禁用查询缓存（
CommandFlags.NoCache
），避免缓存污染或调试时结果不准启用非缓冲读取（
CommandFlags.None
），处理百万级结果不爆内存混合使用事务、命令类型（
CommandType.StoredProcedure
）、自定义标志 复用同一组配置（如统一加审计参数、日志标记）

CommandDefinition 的核心参数怎么填

它本质是 SQL 执行的“配置包”，构造时最常用的是带命名参数的重载：

var cmd = new CommandDefinition(
    sql: "SELECT * FROM Orders WHERE Status = @Status AND CreatedAt > @Since",
    param: new { Status = "Shipped", Since = DateTime.Today.AddDays(-7) },
    commandTimeout: 45,
    commandType: CommandType.Text,
    flags: CommandFlags.Buffered // 或 CommandFlags.None / CommandFlags.NoCache
);

注意几点：

param
支持匿名对象、
IDictionary
、自定义类，Dapper 自动展开为命名参数
commandTimeout
单位是秒，优先级高于连接字符串里的
Connect Timeout

flags
是位标志，可组合：比如
CommandFlags.NoCache | CommandFlags.Pipelined
不传
commandTimeout
或传
null
，就走数据库驱动默认值（通常 30 秒）

配合高级 SQL 特性一起用

Dapper 本身不解析 SQL，所以窗口函数、CTE、动态分页这些全靠你写标准 SQL，

CommandDefinition

只负责稳稳执行它：

用 CTE 做递归组织树：
WITH Org AS ( ... ) SELECT * FROM Org
，照常传入
CommandDefinition
用窗口函数分页：
ROW_NUMBER() OVER (ORDER BY Id) AS RowNum
，映射到含
RowNum
属性的类即可动态构建 SQL 时（比如用
Dapper.SqlBuilder
），最后调用
builder.AddParameters()
得到
object param
，再塞进
CommandDefinition

异步场景下怎么传

所有

*Async

方法（如

QueryAsync<t></t>

）都支持直接传

CommandDefinition

，且能同时用

CancellationToken

：

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var cmd = new CommandDefinition(sql, param, commandTimeout: 30);
var list = await conn.QueryAsync<Order>(cmd, cancellationToken: cts.Token);

这样既控了命令超时，又支持用户主动取消，双重保障。

基本上就这些。不用硬记所有字段，抓住“SQL + 参数 + 超时 + 标志”四要素，高级查询构造就稳了。