C#/.NET调用QuickBooks Desktop SDK获取客户备注列表异常

云原生阿岚

2026-8-27

问题现象

调用QuickBooks SDK拉取客户备注（Customer Notes）时持续出现异常：

接口默认仅返回第一条备注内容，无法获取完整的备注列表
读取AdditionalNotesRetList属性时，属性值始终为null
当前使用环境为32位QuickBooks SDK 15版本，官方标注该版本兼容覆盖QuickBooks 2002-2022全系列产品

复现代码如下：

QBSessionManager sessionManager = null;
bool sessionBegun = false;
bool connectionOpen = false;
try
{
    sessionManager = new QBSessionManager();
    sessionManager.OpenConnection("", "Company2");
    connectionOpen = true;
    sessionManager.BeginSession(@"C:\Users\Public\Documents\Intuit\QuickBooks\Company Files\Company2.qbw", ENOpenMode.omDontCare);
    sessionBegun = true;

    IMsgSetRequest requestMsgSet = sessionManager.CreateMsgSetRequest("US", 8, 0);
    requestMsgSet.Attributes.OnError = ENRqOnError.roeContinue;

    ICustomerQuery customerQueryRq = requestMsgSet.AppendCustomerQueryRq();

    IMsgSetResponse responseMsgSet = sessionManager.DoRequests(requestMsgSet);
    IResponse response = responseMsgSet.ResponseList.GetAt(0);
    ICustomerRetList customerRetList = (ICustomerRetList)response.Detail;
    ICustomerRet customerRet = customerRetList.GetAt(0);

    // customerRet.AdditionalNotesRetList is null
    IAdditionalNotesRetList listnotes = (IAdditionalNotesRetList)customerRet.AdditionalNotesRetList;

}
catch (Exception ex)
{
    throw;
}

问题根因

问题出在消息集请求的版本声明上：代码中创建IMsgSetRequest时指定的版本为8.0，该版本是对应QuickBooks 2004的早期规范，AdditionalNotesRetList字段是从消息集版本12.0才开始新增支持的返回字段。低版本请求下，SDK只会返回最早版本就存在的Notes字段（即单条第一条备注），后续新增的附加备注列表字段不会被序列化返回，因此读取时始终为null。

修复方案

将消息集请求的版本号调整为当前SDK支持的高版本，15版本SDK对应支持的最高消息集版本为15.0，修改对应代码行即可：

// 原低版本声明：IMsgSetRequest requestMsgSet = sessionManager.CreateMsgSetRequest("US", 8, 0);
IMsgSetRequest requestMsgSet = sessionManager.CreateMsgSetRequest("US", 15, 0);

版本修改后无需额外配置，重新发起请求即可正常读取AdditionalNotesRetList属性，遍历集合就能拿到全量备注内容。

注：高版本消息集完全向下兼容老版本QuickBooks客户端，不会因为指定了15.0版本就无法连接2002-2021区间的低版本QuickBooks，SDK会自动做字段兼容处理，不会抛出兼容性错误。

内容的提问来源于stack exchange，提问作者Fazeel Mehar