.NET 6控制台项目拷贝至其他机器后触发Microsoft.Data.SqlClient文件未找到异常

异常核心原因与缺失依赖 #

• 本质是依赖缺失，具体缺失的就是异常信息里明确指出的Microsoft.Data.SqlClient（版本4.1.0.0）程序集。本地开发环境中，该依赖要么存在于NuGet缓存，要么构建时已被复制到输出目录；但拷贝到目标机器时，这个关键依赖文件未被包含在转移的文件夹内。

为何抛出文件未找到异常 #

.NET运行时加载程序集时，会先在预设路径（如程序输出目录、全局程序集缓存GAC等）查找匹配版本的.dll文件。当完全找不到对应文件时，CLR会直接抛出FileNotFoundException——这是程序集加载流程的标准触发逻辑，因为连文件都找不到，根本无法进入版本校验、依赖冲突等后续环节，因此不会抛出其他类型的异常。

排查与解决步骤 #

• 直接检查目标机器的输出文件夹：确认是否存在Microsoft.Data.SqlClient.dll，右键查看文件属性→详细信息，核对版本是否为4.1.0.0。
• 核对本地构建/发布模式：
  • 如果用的是框架依赖部署（FDD），目标机器需要安装对应版本的.NET 6运行时，且运行时需包含Microsoft.Data.SqlClient依赖；若目标机器未安装匹配运行时或运行时缺少该组件，就会报错。
  • 如果是独立部署（SCD），发布时应自动打包所有依赖，若未包含则说明发布配置有问题，需重新检查发布设置。
• 检查项目依赖配置：打开项目的.csproj文件，查看Microsoft.Data.SqlClient的依赖项是否设置了PrivateAssets="All"或CopyLocal=false——这类配置会导致构建时不将该dll复制到输出目录。
• 启用程序集加载日志：在目标机器的命令行中执行以下命令，再启动程序，生成的日志会详细记录运行时搜索程序集的路径及失败原因：

  set COMPLUS_LogEnable=1
  set COMPLUS_LogPath=C:\Temp\AssemblyLoadLog
  

  （需确保C:\Temp目录存在）
• 重新发布测试：使用Visual Studio的发布功能，选择“文件夹”作为目标，将部署模式设为“独立”，勾选“生成单一文件”（可选），然后将完整发布文件夹拷贝到目标机器运行。

内容的提问来源于stack exchange，提问作者Elroy Flynn