.NET Framework 4.8 SDK风格项目引用为何需添加HintPath？

我正尝试把基于.NET Framework 4.8的项目从旧格式.csproj迁移到新的SDK风格格式，碰到了第三方依赖引用的问题——这类依赖既不是NuGet包、不在GAC里，也不是自己的项目（比如预安装的UFT Developer SDK），这个问题适用于所有类似的第三方依赖场景。

旧格式的引用写法：

<Reference Include="HP.LFT.Report" />

新格式里必须加HintPath才能生效（绝对或相对路径都可以）：

<Reference Include="HP.LFT.Report">
  <HintPath>C:\Program Files (x86)\Micro Focus\UFT Developer\SDK\DotNet\HP.LFT.Report.dll</HintPath>
</Reference>

我的疑问：

• 为什么新格式必须加HintPath？
• HintPath会随时间或机器不同变化，有没有其他办法让MSBuild找到这些依赖？
• 新格式里加这类引用的正确方式是什么？

为什么新格式需要HintPath？ #

旧的非SDK风格项目默认包含更多搜索路径，比如系统默认的程序集安装目录、项目本地bin目录等，MSBuild会自动遍历这些路径找匹配的程序集。而SDK风格项目为了更简洁、避免依赖查找歧义（比如不同版本Newtonsoft.Json冲突），默认缩小了程序集搜索范围，只优先找NuGet包、GAC和项目引用，对不在这些范围内的第三方预安装程序集，必须明确指定HintPath告诉MSBuild具体位置。

替代HintPath的解决方案 #

1. 用环境变量 #

可以用环境变量代替硬编码的绝对路径，不同机器配置同名环境变量指向各自的SDK安装路径，然后在csproj里引用：

<Reference Include="HP.LFT.Report">
  <HintPath>$(UFT_DEVELOPER_SDK_PATH)\DotNet\HP.LFT.Report.dll</HintPath>
</Reference>

需要在系统或用户环境变量里加UFT_DEVELOPER_SDK_PATH，值设为C:\Program Files (x86)\Micro Focus\UFT Developer\SDK（根据实际安装路径调整）。

2. 自定义MSBuild搜索路径 #

在项目文件或Directory.Build.props里添加自定义的程序集搜索目录，让MSBuild自动查找：

<PropertyGroup>
  <AssemblySearchPaths>$(AssemblySearchPaths);C:\Program Files (x86)\Micro Focus\UFT Developer\SDK\DotNet</AssemblySearchPaths>
</PropertyGroup>

这样就能像旧格式一样直接写<Reference Include="HP.LFT.Report" />，MSBuild会在自定义路径里找。要适配不同机器的话，同样可以结合环境变量：

<PropertyGroup>
  <AssemblySearchPaths>$(AssemblySearchPaths);$(UFT_DEVELOPER_SDK_PATH)\DotNet</AssemblySearchPaths>
</PropertyGroup>

3. 复制依赖到项目本地 #

把第三方DLL复制到项目的本地目录（比如lib文件夹），然后用相对路径的HintPath：

<Reference Include="HP.LFT.Report">
  <HintPath>..\lib\HP.LFT.Report.dll</HintPath>
</Reference>

这种方式能避免路径不一致的问题，但要维护本地的DLL版本，适合依赖版本稳定的场景。

新格式里添加此类引用的正确方式 #

优先推荐结合环境变量的自定义搜索路径，既避免硬编码路径的麻烦，又能保持项目配置简洁。如果依赖版本固定，复制到项目本地也是可靠的方案。尽量别直接用绝对路径的HintPath，除非是单机器的个人项目。

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