升级System.Data.SqlClient至Microsoft.Data.SqlClient时遭遇TypeLoadException异常

阿华AIGC实验室

2026-4-8

兄弟，我之前升级这个组件的时候也踩过一模一样的坑！你这种情况大概率是依赖版本不统一或者程序集加载冲突导致的，毕竟System.Data.SqlClient和Microsoft.Data.SqlClient虽然API大部分兼容，但底层的程序集标识完全不同，很容易出加载异常。给你分享几个亲测有效的排查解决步骤：

强制统一项目依赖版本
你的私有NuGet包已经升级到Microsoft.Data.SqlClient 6.0.2了，但一定要确保Web API项目本身也直接安装相同版本的Microsoft.Data.SqlClient，别让它通过私有包间接引用（很可能拉到旧版本）。你可以打开Web API项目的NuGet包管理器，直接搜索安装6.0.2版本，把依赖版本锁死。
手动指定程序集绑定规则
虽然ASP.NET Core默认会处理大部分程序集绑定，但有时候还是得手动兜底。你可以在Web API项目的runtimeconfig.template.json里添加如下配置，强制所有地方都加载正确版本的程序集：
```
{
  "runtimeOptions": {
    "assemblyBinding": {
      "dependencies": {
        "Microsoft.Data.SqlClient": {
          "assemblyVersion": "6.0.2.0",
          "publicKeyToken": "23ec7fc2d6eaa4a5"
        }
      }
    }
  }
}
```
注意公钥令牌要和Microsoft.Data.SqlClient的官方值一致，别写错了。
清理缓存+全量重建
本地的bin、obj缓存真的是很多诡异问题的源头！先把私有NuGet包项目和Web API项目的bin、obj文件夹全删掉，然后重新构建私有包并发布到你的私有源，再回到Web API项目更新包引用，最后清理整个解决方案再重新构建一次，别嫌麻烦，很多时候清完缓存问题就没了。
检查Dapper版本兼容性
虽然Dapper对Microsoft.Data.SqlClient支持不错，但旧版本的Dapper可能存在兼容问题。你可以把Dapper升级到最新的稳定版（至少2.0.123及以上），确保它能正确识别新的SqlClient程序集类型。
深挖异常细节
你可以把TypeLoadException的完整堆栈信息打印出来，看看具体是找不到哪个类型、哪个程序集。比如有没有漏改的引用——比如某个地方还在写using System.Data.SqlClient;而不是using Microsoft.Data.SqlClient;，或者自定义的扩展方法还在依赖旧的SqlConnection类型，这种情况也会触发加载异常。