简介：面向VC++数据库开发学习者的ADO Command对象实例包，围绕_CommandPtr智能指针演示在MFC/VC++工程中执行SQL与存储过程的方法，适合已具备ADO连接基础、希望掌握参数化查询和异常处理的中初级开发者参考。压缩包共11个文件，以3个cpp源文件和3个头文件为核心，配合sln解决方案、vcxproj工程配置及说明文本，整体约8KB，以单工程方式组织，便于打开工程对照阅读。目前已有528人学习，反映出该主题在VC++数据访问实践中具有一定关注度。示例代码覆盖Command对象的创建与连接绑定、CommandText和CommandType属性设置、通过Parameter追加输入参数、调用存储过程以及Execute返回结果集或影响行数等环节，并提示加入try-catch错误处理；同时包含事件处理代码，便于观察命令执行回调与异常分支。读者可据此梳理ADO命令执行流程，理解参数类型、方向与长度的设置方式，比较参数化查询和存储过程调用的差异，并借助工程结构快速定位代码，为课程实验和后续数据库模块开发提供参考。

1. 参数全是 0 的那次上线：Command 对象该在什么时候出手

参数全是 0，SQL 不报错，日志里干干净净——第一次在 VC++ 工程里用_CommandPtr的人，多半都撞过这个场面。ADO 的 Command 对象干的是一件很窄的事：把一条带占位符的 SQL 和一组参数打包，交给 OLE DB 提供程序去执行。它的价值不在「能执行 SQL」，而在「同一条语句被执行很多次，参数只换值不换结构」。只拼字符串查一次，Command 反而是负担；一旦涉及存储过程、输出参数、循环写入、事务边界，它就是绕不开的那一层。这份 Ado 实例把_ConnectionPtr、_CommandPtr、_ParameterPtr三者的关系用可编译的代码串了一遍，适合手上有 VC++ 老工程、要接手数据库访问层的人照着改。

2. 接线：从 #import 到 _CommandPtr，五行代码里的四个决定

VC++ 里用 ADO 不需要装 SDK，也不需要链 lib，全部靠#import读类型库现场生成_com_ptr_t智能指针包装。这一步做对了，后面写起来就是普通的 C++；做错了，你会收获一堆_com_error和看不懂的 HRESULT。

2.1 #import 那一行里的 rename 与命名空间选择

标准写法是这么一行，通常只放在预编译头里，全工程共用：

// pch.h 里只 import 一次；在多个头文件里重复 #import 会导致类型重复定义 #import "C:\Program Files\Common Files\System\ado\msado15.dll" \ no_namespace \ rename("EOF", "adoEOF") \ rename("BOF", "adoBOF") \ rename("GetObject", "adoGetObject")

三个 rename 是保命用的。EOF和BOF在不少 C 运行库头文件里是宏，不重命名会在你写rs->adoEOF之前就编译失败；GetObject在图形相关头文件里是宏，冲突后报的错完全指不到 ADO 上。no_namespace让adCmdText、adVarWChar这些枚举直接全局可用；如果你保留命名空间，就得写ADODB::adCmdText，代码里外要多敲很多字。类型库路径建议写成本机绝对路径，靠 PATH 搜索在干净环境里经常找不到文件——这类问题在编译机上排查起来特别费时间。

编译一次之后，编译器会生成msado15.tlh和msado15.tli两个文件，前者是接口声明，后者是内联实现。想确认某个常量到底叫什么、某个属性是什么类型，直接翻.tlh比查文档快。

2.2 从连接串到 CreateInstance：一个能跑起来的最小骨架

连接串里的关键字由 OLE DB 提供程序决定，不同提供程序用的词不一样（有的叫Data Source，有的叫Server；有的用Initial Catalog，有的用Database）。我一般把它放在配置文件里，代码只负责读字符串，这样换环境不用重编。

#include <comdef.h> class CDbSession { public: bool Open(const wchar_t* connStr) { // ADO 是套间模型，用单线程套间足够；每个真正用它的线程都要初始化一次 ::CoInitializeEx(NULL, COINIT_APARTMENTTHREADED); try { m_conn.CreateInstance(__uuidof(Connection)); // 等价 CoCreateInstance + 包装 m_conn->ConnectionTimeout = 10; // 建连超时，秒 m_conn->CommandTimeout = 30; // 单条命令执行超时，秒 m_conn->Open(_bstr_t(connStr), L"", L"", adConnectUnspecified); return true; } catch (const _com_error& e) { m_lastErr = e.Description(); return false; } } _ConnectionPtr Conn() const { return m_conn; } private: _ConnectionPtr m_conn; _bstr_t m_lastErr; };

CreateInstance是_com_ptr_t提供的语法糖，内部还是在做CoCreateInstance，只是省掉了IID_和void**的强转。Open的第三、四个参数是用户名和密码，如果连接串里已经带了账号口令就传空串，别两处都写——两处不一致时以连接串为准，排查时会怀疑人生。

拿到连接之后，Command 有两种挂法：

_CommandPtr cmd; cmd.CreateInstance(__uuidof(Command)); cmd->ActiveConnection = m_conn; // 推荐：挂到已有连接上 // cmd->ActiveConnection = _variant_t(connStr); // 不推荐：命令会自建一条连接

第二种写法看着省事，实际上是个坑：每次执行都会新开一条连接，事务管不到它，连接池也会被打爆。除非你明确需要一个独立于当前会话的命令，否则一律用第一种。

2.3 Execute 的三个参数：RecordsAffected 是 VARIANT*，别照抄 Connection

_ConnectionPtr::Execute和_CommandPtr::Execute的签名不一样，这是最容易凭印象写错的地方：

_variant_t vtAffected; _RecordsetPtr rs; try { // Command::Execute(RecordsAffected, Parameters, Options) rs = cmd->Execute(&vtAffected, NULL, adCmdText); } catch (const _com_error& e) { // 见第 5 章：这里要把 Errors 集合捞出来 throw; } long nAffected = (vtAffected.vt == VT_I4) ? vtAffected.lVal : 0; while (rs && !rs->adoEOF) { _bstr_t orderNo = rs->Fields->GetItem(_variant_t((long)0))->Value; double amount = rs->Fields->GetItem(_variant_t((long)1))->Value; rs->MoveNext(); } rs->Close(); // 不关会在下一次执行时撞上「连接繁忙」

第一个参数是VARIANT*，不是long*；好在它回来一般是VT_I4，取之前判一下vt类型更保险。第二个参数是「参数值数组」，几乎没人用，老老实实传NULL，参数走Parameters集合。第三个参数Options是给提供程序的提示：adCmdText是普通 SQL，adCmdStoredProc是存储过程，再与adExecuteNoRecords（0x80）按位或，就得到「这条语句不回结果集，别构建 Recordset」的组合值。

对纯 INSERT/UPDATE/DELETE，把adExecuteNoRecords加上去能省掉一次结果集对象的构造，循环里差别能看出来：

_variant_t vtAffected; cmd->Execute(&vtAffected, NULL, adCmdText | adExecuteNoRecords);

3. 参数绑定：CreateParameter 的四个字段，错一个就查不出数据

参数化是 Command 存在的核心理由。它把 SQL 文本和值彻底分开，值走二进制绑定的通道，既躲开了拼接 SQL 的引号转义地狱，也让提供程序有机会复用执行计划。

3.1 Append 的顺序与四个必填字段

CreateParameter的参数依次是：名字、数据类型、方向、长度、值。

_CommandPtr cmd; cmd.CreateInstance(__uuidof(Command)); cmd->ActiveConnection = conn; cmd->CommandType = adCmdText; cmd->CommandText = L"select order_no, amount from t_order " L"where dept_id = ? and buyer like ? and created_at >= ?"; // 1) 整型：Size 对定长类型没有意义，填 0 _ParameterPtr pDept = cmd->CreateParameter(L"@dept", adInteger, adParamInput, 0, _variant_t((long)1001)); cmd->Parameters->Append(pDept); // 2) 变长宽字符：Size 是"字符数"，不是字节数，必须给，否则有的提供程序按 0 处理 _ParameterPtr pBuyer = cmd->CreateParameter(L"@buyer", adVarWChar, adParamInput, 64, _variant_t(L"某")); cmd->Parameters->Append(pBuyer); // 3) 时间：用 VT_DATE 的 _variant_t，别传字符串让数据库隐式转换 COleDateTime dt(2024, 3, 1, 0, 0, 0); _ParameterPtr pTime = cmd->CreateParameter(L"@t", adDBTimeStamp, adParamInput, 0, _variant_t(dt)); cmd->Parameters->Append(pTime);

?占位符是位置绑定，Append的顺序必须和 SQL 里问号出现的顺序完全一致。名字（@dept之类）对adCmdText其实不起作用，但强烈建议写清楚——半年后回头改代码，名字是唯一的线索。adParamInput也不能省，虽然默认值就是它，显式写出来跟输出参数放在一起时不会看错。

还有一点：CommandText要在Append之前设好。反过来的顺序在多数提供程序上也能跑，但一旦涉及存储过程或提供程序做语句预解析，参数集合就会和语句对不上，表现为「参数个数不匹配」或者干脆静默取到默认值。

3.2 类型对照表与三个容易设错的属性

DataTypeEnum有几十个值，实际项目里常用的就那几个。下面这张表是我这些年反复对照的一张：

adNumeric的两个附加属性要在Append之后单独赋值：

_ParameterPtr pAmt = cmd->CreateParameter(L"@amt", adNumeric, adParamInput, 0, _variant_t(L"12345.67")); pAmt->Precision = 18; // 总位数 pAmt->NumericScale = 2; // 小数位 cmd->Parameters->Append(pAmt);

不设这两个属性时，有的提供程序会按默认精度截断，五位数的金额变成两位数是真事。另外_variant_t存金额建议直接用字符串构造，避免 C++double的二进制表示在转换时引入误差。

3.3 存储过程：Refresh 拿到命名参数、输出参数与返回值

调存储过程有两种写法。手工建参数可控但啰嗦，Refresh省事但多一次网络往返：

cmd->ActiveConnection = conn; // Refresh 之前必须先挂连接 cmd->CommandType = adCmdStoredProc; cmd->CommandText = L"p_query_order"; cmd->Parameters->Refresh(); // 让提供程序回填参数定义（一次往返） // 输入参数按名字取，不用关心顺序 cmd->Parameters->GetItem(_variant_t(L"@dept"))->Value = _variant_t((long)1001); cmd->Parameters->GetItem(_variant_t(L"@total"))->Value = _variant_t((long)0); // 输出参数先占位 _variant_t vtAffected; _RecordsetPtr rs = cmd->Execute(&vtAffected, NULL, adCmdStoredProc); rs->Close(); long nTotal = (long)cmd->Parameters->GetItem(_variant_t(L"@total"))->Value;

Refresh之后参数集合里会出现过程定义里的全部参数，包括adParamOutput和位于索引 0 的返回值参数（adParamReturnValue）。此时不要再手工Append，否则会出现两份同名参数，执行时报参数个数不匹配。

如果提供程序不支持Refresh（Refresh之后Count还是 0，或者类型是adParamUnknown），退回手工建参数，并且必须严格按过程定义的顺序Append，含返回值参数放第一位。这个兼容性问题在老版本提供程序上很常见，写代码时留个if (cmd->Parameters->Count == 0)的分支会省很多事。

4. 复用：Prepared、事务归属与循环里的同一个 _CommandPtr

Command 相对Connection::Execute的唯一结构性优势就是复用。但「复用」这件事在 ADO 里有三个层次，搞错了不但不提速，还会引入难查的错。

4.1 Prepared 什么时候真的有用

cmd->CommandText = L"update t_stock set qty = ? where sku = ?"; cmd->CommandType = adCmdText; _ParameterPtr pQty = cmd->CreateParameter(L"@qty", adInteger, adParamInput, 0, _variant_t((long)0)); _ParameterPtr pSku = cmd->CreateParameter(L"@sku", adVarWChar, adParamInput, 32, _variant_t(L"")); cmd->Parameters->Append(pQty); cmd->Parameters->Append(pSku); cmd->Prepared = VARIANT_TRUE; // 必须在参数集合齐全之后、第一次 Execute 之前设

Prepared的含义是「让提供程序把这条语句编译好留着」，代价是第一次执行多一次往返。它的有效期严格绑定在：同一条连接、同一个 CommandText、同一套参数类型和个数。以下任一情况发生，之前的准备工作就作废了：改了CommandText、增删了参数、连接被关闭重开、连接池把底层会话换掉。

我在一个批量更新的场景里量过：单条循环两千次，加上Prepared和不加，总耗时差异在 10% 上下；而把两千次往返改成一条多值 UPDATE，耗时直接掉到原来的十几分之一。结论很直白——先减少往返次数，再谈 Prepared。顺序反了就是在做无效优化。

还有一个副作用要知道：Prepared之后单次执行实际是「准备 + 执行」两步，CommandTimeout卡的是整条命令，超时值要给得比不加时宽一点，否则慢语句会在准备阶段就超时。

4.2 事务边界与连接归属

事务是_ConnectionPtr上的方法，不是 Command 上的：

conn->BeginTrans(); try { for (size_t i = 0; i < rows.size(); ++i) { cmd->Parameters->GetItem(_variant_t((long)1))->Value = _variant_t((long)rows[i].qty); cmd->Parameters->GetItem(_variant_t((long)2))->Value = _variant_t(rows[i].sku.c_str()); _variant_t vtAffected; cmd->Execute(&vtAffected, NULL, adCmdText | adExecuteNoRecords); } conn->CommitTrans(); } catch (const _com_error& e) { conn->RollbackTrans(); // 失败一定要回滚，否则连接会带着未提交事务被放回池里 throw; }

这里的关键是连接归属。上面这段能回滚，前提是cmd->ActiveConnection指向的就是conn这个对象。如果 Command 的ActiveConnection当初是用连接串赋的值，它自己开了一条连接，那么conn->BeginTrans()对它完全无效——数据照写，回滚照失败，而且不会报任何错。

BeginTrans的返回值是嵌套层数，支持嵌套事务（内层提交只是减计数）。实际项目里我一般不允许嵌套，事务只在服务层开一层，DAO 层的方法只负责执行，谁开谁提交，边界清晰，出问题好定位。

4.3 循环里复用同一个 _CommandPtr 的写法

复用最容易犯的错不是忘设参数，而是在循环里重复 Append：

// 错误示范：循环里 Append，Parameters 集合越滚越大，最后报参数个数不匹配 for (size_t i = 0; i < rows.size(); ++i) { cmd->Parameters->Append(cmd->CreateParameter(L"@sku", adVarWChar, adParamInput, 32, _variant_t(rows[i].sku.c_str()))); cmd->Execute(&vtAffected, NULL, adCmdText | adExecuteNoRecords); }

正确做法是循环外建参数，循环内只改Value：

// 正确：建一次，改值 N 次 for (size_t i = 0; i < rows.size(); ++i) { cmd->Parameters->GetItem(_variant_t((long)1))->Value = _variant_t((long)rows[i].qty); cmd->Parameters->GetItem(_variant_t((long)2))->Value = _variant_t(rows[i].sku.c_str()); _variant_t vtAffected; cmd->Execute(&vtAffected, NULL, adCmdText | adExecuteNoRecords); }

用序号取参数比按名字取快，因为按名字取要枚举集合。序号从 1 开始，这是 ADO 集合的统一约定，从 0 开始会直接抛「索引无效」。

三种批量写法的取舍，我的经验是这样：

规模上了万，单靠 ADO 循环已经不合适了，该走批量导入通道，那是另一个话题。

5. 避坑排查：五类 Command 报错的现场还原与处置

5.1 参数全是 0 或空串，SQL 却执行成功

现象：同一条 SQL 在客户端工具里带实参能查出数据，程序里跑出来零行，或写入的值全是默认值，日志里没有任何异常。

原因：类型对不上。最常见的是Size给 0 的变长参数，某些提供程序直接按空值绑定；其次是_variant_t被短整型构造（_variant_t((short)1001)生成 VT_I2），而参数声明的是adInteger，取值时被当成 0。

解决：在Execute之前把每个参数打出来自检一遍，vt字段是判断依据。

for (long i = 1; i <= cmd->Parameters->Count; ++i) { _ParameterPtr p = cmd->Parameters->GetItem(_variant_t(i)); _variant_t v = p->Value; TRACE(L"param %d: type=%d vt=%d size=%d\n", i, p->Type, v.vt, p->Size); }

v.vt该是VT_I4（整型）、VT_BSTR（字符串）、VT_DATE（时间），和p->Type一一对上才往下走。

5.2 「连接正忙于处理其他命令的结果」

现象：循环执行到第二轮开始抛_com_error，错误描述大意是连接上还有未取完的结果；单独跑一次却完全正常。

原因：上一个_RecordsetPtr没有Close()，或者用adCmdText一次提交了多条语句产生了多个结果集，只处理了第一个。

解决：给 Recordset 加作用域，用完立刻关；确实需要多结果集时用rs->NextRecordset()逐个消费到底。另外，_RecordsetPtr是智能指针，作用域结束会自动Release，但不会自动 Close，底层游标仍然占着连接。

{ _RecordsetPtr rs = cmd->Execute(&vtAffected, NULL, adCmdText); // ... 读数据 rs->Close(); // 显式关，别指望析构 }

5.3 存储过程的输出参数永远是 0

现象：过程单独执行能返回计数，程序里读出来是 0，或者干脆读到空。

原因：三种可能——建参数时方向写成了adParamInput；Refresh之后又手工Append了一遍，读到的是前面那个没被赋值的；读取时机在Execute之前。

解决：Refresh之后只用GetItem按名字改值，不再Append；读取一定放在Execute返回之后，并且先Close掉返回的 Recordset 再取参数值。

5.4 报错信息只有半句，看不出所以然

现象：catch到的e.Description()里只有一句很泛的描述，跟实际原因（字段超长、唯一键冲突）完全对不上。

原因：_com_error携带的是 HRESULT 层面的描述，提供程序返回的详细消息在Connection的Errors集合里，而且这个集合在下一条语句执行时会被清空。等你在别处再去看，早就没了。

解决：catch里立刻遍历，并和e的信息拼在一起。

catch (const _com_error& e) { CString msg; msg.Format(L"HRESULT=0x%08X src=%s desc=%s", e.Error(), (LPCWSTR)e.Source(), (LPCWSTR)e.Description()); if (conn && conn->Errors->Count > 0) { for (long i = 0; i < conn->Errors->Count; ++i) { _ErrorPtr err = conn->Errors->GetItem(_variant_t(i)); msg.AppendFormat(L" | [%d] %s (native=%ld)", i, (LPCWSTR)err->Description, err->NativeError); } } throw; }

NativeError是提供程序自己的错误码，定位「字段超长」这类问题时比 HRESULT 有用得多。这段代码看着啰嗦，但它就是排查时的后悔药，一次写好，后面所有失败都靠它。

5.5 退出或切线程时崩溃，堆栈指向 COM 释放

现象：主线程跑得好好的，程序退出时崩在某个Release上；或者把连接对象丢给工作线程用，偶发访问冲突。

原因：ADO 对象是套间级的，不能跨套间直接传递接口指针；工作线程如果没调用CoInitializeEx，CreateInstance会直接失败或者返回一个不能用的对象。

解决：每个真正操作数据库的线程自己CoInitializeEx(NULL, COINIT_APARTMENTTHREADED)，自己建连接和命令对象，线程结束时CoUninitialize()。不要图省事在 UI 线程建好对象再传给工作线程——那是玄学崩溃的源头，重现率极低，排查成本极高。

6. 收口：一个三十行的执行封装和上线前的自检习惯

写到这里，把前面散落的细节收成一个能直接放进项目的小封装，剩下的业务代码就只剩「设参数、取结果」两件事：

// 无结果集语句统一入口；lOptions 传 adCmdText / adCmdStoredProc long ExecNoRecords(const _CommandPtr& cmd, long lOptions, _ConnectionPtr& conn) { _variant_t vtAffected; try { cmd->Execute(&vtAffected, NULL, lOptions | adExecuteNoRecords); } catch (const _com_error& e) { LogAdoError(e, conn); // 第 5.4 节那段 throw; } return (vtAffected.vt == VT_I4) ? vtAffected.lVal : 0; } // 查询语句统一入口；调用方负责 Close _RecordsetPtr ExecQuery(const _CommandPtr& cmd, long lOptions, _ConnectionPtr& conn) { _variant_t vtAffected; try { return cmd->Execute(&vtAffected, NULL, lOptions); } catch (const _com_error& e) { LogAdoError(e, conn); throw; } }

封装本身没什么技术含量，价值在于入口收敛。所有 Command 的执行都走这两个函数，超时、错误日志、adExecuteNoRecords的取舍就只有一处需要维护，新人接手也不会各处各写一套。

配套的自检清单，我在提交数据库访问层代码之前会强制过一遍：

最后一条血泪经验：不要相信「这个参数反正不会超长」。我吃过一次亏，一个Size给 64 的字段被塞进 80 个字符，提供程序没报错，直接截断，脏数据在库里躺了三个月才被发现。从那以后我每次加新参数，都会顺手把Size按实际长度的两倍给足，并在封装里加一条断言，长度超了当场抛。希望帮到你。

本文还有配套的精品资源，点击获取