MSBuild ProjectReference 项文档

Question

我在 MSBuild 项目中找不到有关 ProjectReference 标记的文档。我在哪里可以阅读它的详细说明？

编辑： 我有一个由其他人创建的.vcxproj。它包含ProjectReference 项目。 ProjectReference 包含子标签：Private、ReferenceOutputAssembly、CopyLocalSatelliteAssemblies、LinkLibraryDependencies、UseLibraryDependencyInputs。我在哪里可以阅读这些标签？它们可以包含哪些值？ ProjectReference 还可以包含哪些其他子标签？

我在 MSDN 和 Google 中搜索过，但没有找到文档页面，只有关于其他产品的讨论和文档，而不是 MSBuild。

Answer 1

从 Jason Pyeron 在他的评论中提供的 MSBuild 源代码链接开始，我了解到，当 MSBuild 准备构建依赖项时，每个 ProjectReference 项目中的 it includes all item metadata（您称为子标签）。因此，下游任务和目标可以并且有时确实可以读取任意 ProjectReference 元数据。

有关 C++ 项目的问题的答案，您可以检查 Microsoft.CppBuild.targets 和 Microsoft.CppCommon.targets（它们在 MSBuild 14 中的默认路径，与 Visual Studio 2015 一致，是 C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140\）。然而，如下例所示，这样做并不简单：

1. 在Microsoft.CppBuild.targets 中，目标ResolvedXDCMake 动态创建_ResolvedNativeProjectReferencePaths 项目。
2. 目标 ComputeReferenceLinkInputs 从这些项目中动态创建 ProjectReferenceToLink 项目。
3. 对于每个没有 CopyLocal 元数据的项目，相同的目标会添加它，复制任何 Private 元数据值。
4. 对于每个具有不同路径的项目，同一目标会动态创建一个Link 项目。
5. 现在切换到Microsoft.CppCommon.targets，Link 项目在Link 目标的Sources 参数中传递！虽然公平地说，它们的元数据在上一步中已被清除，因此在这种特殊情况下，您不必深入研究Link Target 文档。

以下是与您的问题相关的其他部分：

参数

• Include（属性）：项目文件路径
• Project（元数据）：项目 GUID，格式为 {00000000-0000-0000-0000-000000000000}
• ReferenceOutputAssembly（元数据）：布尔值，指定是否 引用的项目的输出应传递给编译器。 默认为 true。
• SpecificVersion（元数据）：是否应使用程序集的确切版本。
• Targets（元数据）：应构建的引用项目中以分号分隔的目标列表。默认为$(ProjectReferenceBuildTargets)的值，默认为空，表示默认目标。
• OutputItemType（元数据）：要向其中发出目标输出的项目类型。默认为空白。如果ReferenceOutputAssembly 设置为“true”（默认），那么目标输出将成为编译器的引用。
• EmbedInteropTypes（元数据）：可选布尔值。此引用中的类型是否需要嵌入到目标程序集中 - 仅限互操作程序集

备注

当使用OutputItemType 参数时，其他参数（元数据）可能适用。比如OutputItemType设置为Content，就可以使用CopyToOutputDirectory：

• CopyToOutputDirectory（元数据）：可选字符串。确定是否将文件复制到输出目录。值：Never、Always、PreserveNewest。

Answer 2

您会注意到 ProjectReference 元素是 ItemGroup 元素的子元素。

值得庆幸的是，ItemGroups 是一个完整记录的架构项目。您会发现 ItemGroups 的子元素可以是任何东西。将其视为集合的名称。 ItemGroup 中的那个项目可以有“元数据”值。

例如，

<ItemGroup>
    <WindowsFiles Include="C:\Windows\*">
       <IsSystem>true</IsSystem>
    </WindowsFiles>
</ItemGroup>

这是定义一个名为 WindowsFiles 的项目组。它本质上变成了与 Include 属性匹配的文件集合。所有项目组项目都有内置的元数据 - 例如文件名、扩展名、完整路径、目录等，但您可以添加自己的 - 在这种情况下 IsSystem 是附加的。

引用项目组通过以下两种方式之一完成：

<Message Text="%(WindowsFiles.FullPath)"/>

<Message Text="@(WindowsFiles->'%(FullPath)')"/>

后者被称为更高级的变换。最好坚持使用前者，直到您完全了解 ItemGroups 或转换不会进入。

您感兴趣的 ProjectReference 项目组将由某个目标文件处理。由于 itemgroup 的名称相当随意，因此从概念上讲它们是变量，因此定义用途的目标文件如何处理它们。

按照导入语句中提到的文件的顺序，查看 ProjectReference 项组的使用位置。

Answer 3

MSDN 上的这个网页似乎有一些很好的信息：

https://docs.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-items?view=vs-2017