Git子模块嵌套依赖的.NET项目调试失败问题排查

核心原因 #

问题根源是解决方案中存在重复的同名程序集项目：你的SampleMicroservice解决方案里同时包含了两个CommonLibrary项目（一个是独立子模块，另一个是嵌套在CommonControllerLibrary子模块里的子模块）。构建时MSBuild会把两个项目的输出都复制到bin目录，但调试时CLR加载程序集会因为程序集标识歧义或加载上下文冲突，无法正确匹配目标程序集。

解决方案 #

1. 移除重复的CommonLibrary项目 #

从解决方案中删除Submodules/CommonLibrary下的独立CommonLibrary项目，只保留CommonControllerLibrary子模块内的CommonLibrary：

• 若SampleMicroservice需要直接引用CommonLibrary，修改项目引用路径为../common-controller-library/common-library/CommonLibrary/CommonLibrary.csproj
• 若无需直接引用，依赖会通过CommonControllerLibrary自动传递，无需额外配置

2. 修正项目引用配置 #

打开SampleMicroservice.csproj，检查所有<ProjectReference>节点，确保没有同时引用两个不同路径的CommonLibrary.csproj：

<!-- 确保只有一个CommonLibrary引用，指向正确的子模块路径 -->
<ProjectReference Include="..\common-controller-library\common-library\CommonLibrary\CommonLibrary.csproj" />
<ProjectReference Include="..\common-controller-library\CommonControllerLibrary\CommonControllerLibrary.csproj" />

3. 清理缓存并重新构建 #

1. 手动删除所有项目的bin和obj文件夹
2. 在Visual Studio中执行「清理解决方案」→「重新生成解决方案」
3. 重启Visual Studio，避免IDE缓存残留

4. 优化Git子模块结构 #

由于CommonControllerLibrary已将CommonLibrary作为嵌套子模块，主项目无需单独添加CommonLibrary子模块：

1. 删除SampleMicroservice根目录下的common-library子模块（执行git submodule deinit -f common-library后删除对应目录）
2. 重新初始化嵌套子模块：git submodule update --init --recursive
3. 调整解决方案项目，仅保留CommonControllerLibrary及其嵌套的CommonLibrary

为什么构建成功但调试失败？ #

构建阶段MSBuild会将所有依赖项目的输出程序集复制到主项目的bin目录，所以你能看到CommonLibrary.dll存在。但调试时CLR加载程序集会检查程序集的完整标识（包括版本、公钥标记、加载上下文），当解决方案中有两个同名同版本的CommonLibrary项目时，CLR可能尝试加载未正确部署的实例，或因两个程序集的生成元数据（如哈希）不同被判定为不同程序集，从而抛出找不到文件的异常。

内容的提问来源于stack exchange，提问作者Alek Davis