Visual C++ 项目扩展性

适用范围：Visual Studio Visual Studio for Mac Visual Studio Code

Visual C++ 项目系统用于 .vcxproj 文件。 它基于 Visual Studio Common Project System (CPS) ，并提供其他特定于 C++ 的扩展点，以便轻松集成新工具集、生成体系结构和目标平台。

所有 .vcxproj 文件都导入这些文件：

这些文件本身定义很少。 相反，它们基于以下属性值导入其他文件：

$(ApplicationType)

示例：Windows 应用商店、Android、Linux

$(ApplicationTypeRevision)

这必须是主要.minor[.build[.revision]格式的有效版本字符串。

示例：1.0、10.0.0.0

$(Platform)

生成体系结构，命名为“平台”，原因为历史原因。

示例：Win32、x86、x64、ARM

$(PlatformToolset)

示例：v140、v141、v141_xp、llvm

这些属性值指定根文件夹下 $(VCTargetsPath) 的文件夹名称：

$(VCTargetsPath)\     应用程序类型\         $(ApplicationType)\             $(ApplicationTypeRevision)\                 平台\                     $(Platform)\                         PlatformToolsets\                             $(PlatformToolset)     平台\         $(Platform)\             PlatformToolsets\                 $(PlatformToolset)

当 $(VCTargetsPath)\ Windows 桌面项目为空时$(ApplicationType)，将使用平台\ 文件夹。

若要添加新的工具集，例如现有 Win32 平台的“MyToolset”，请在\Platform\Win32\PlatformToolsets\下$(VCTargetsPath)创建 MyToolset 文件夹，并在其中创建 Toolset.props 和 Toolset.targets 文件。

PlatformToolsets 下的每个文件夹名称都作为指定平台的可用平台工具集显示在“项目属性”对话框中，如下所示：

在此工具集支持的每个现有平台文件夹中创建类似的 MyToolset 文件夹和 Toolset.props 和 Toolset.targets 文件。

若要添加新平台，例如“MyPlatform”，请在\Platform\下$(VCTargetsPath)创建 MyPlatform 文件夹，并在其中创建 Platform.default.props、Platform.props 和 Platform.targets 文件。 同时创建 $(VCTargetsPath)\Platform\MyPlatform\PlatformToolsets\ 文件夹，并在其中创建至少一个工具集。

每个$(ApplicationType)文件夹的“平台”文件夹下的所有文件夹名称，并$(ApplicationTypeRevision)作为项目的可用平台选项显示在 IDE 中。

的“

若要添加新的应用程序类型，请在 \Application Type\ 下$(VCTargetsPath)创建 MyApplicationType 文件夹，并在其中创建 Defaults.props 文件。 应用程序类型至少需要一个修订，因此还要创建 $(VCTargetsPath)\Application Type\MyApplicationType\1.0 文件夹，并在其中创建 Defaults.props 文件。 还应创建 $(VCTargetsPath)\ApplicationType\MyApplicationType\1.0\Platforms 文件夹，并在其中创建至少一个平台。

$(ApplicationType) 和 $(ApplicationTypeRevision) 属性在用户界面中不可见。 它们在项目模板中定义，在创建项目后无法更改。

Microsoft C++ 属性和目标文件的简化导入树如下所示：

$(VCTargetsPath)\Microsoft.Cpp.Default.props     $(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props     $(VCTargetsPath)\ImportBefore\Default\*。道具     $(VCTargetsPath)\应用程序类型\$(ApplicationType)\Default.props     $(VCTargetsPath)\应用程序类型\$(ApplicationType)\$(ApplicationTypeRevision)\Default.props     $(VCTargetsPath)\应用程序类型\$(ApplicationType)\$(ApplicationTypeRevision)\平台\$(Platform)\Platform.default.props     $(VCTargetsPath)\ImportAfter\Default\*。道具

Windows 桌面项目未定义 $(ApplicationType)，因此它们仅导入

$(VCTargetsPath)\Microsoft.Cpp.Default.props     $(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props     $(VCTargetsPath)\ImportBefore\Default\*。道具     $(VCTargetsPath)\平台\$(Platform)\Platform.default.props     $(VCTargetsPath)\ImportAfter\Default\*。道具

我们将使用该 $(_PlatformFolder) 属性来保存 $(Platform) 平台文件夹位置。 此属性为

$(VCTargetsPath)\平台\$(Platform)

适用于 Windows 桌面应用，以及

$(VCTargetsPath)\应用程序类型\$(ApplicationType)\$(ApplicationTypeRevision)\平台\$(Platform)

对于其他一切。

按以下顺序导入属性文件：

$(VCTargetsPath)\Microsoft.Cpp.props     $(_PlatformFolder)\Platform.props         $(VCTargetsPath)\Microsoft.Cpp.Platform.props             $(_PlatformFolder)\ImportBefore\*。道具             $(_PlatformFolder)\PlatformToolsets\$(PlatformToolset)\Toolset.props             $(_PlatformFolder)\ImportAfter\*。道具

目标文件按以下顺序导入：

$(VCTargetsPath)\Microsoft.Cpp.targets     $(VCTargetsPath)\Microsoft.Cpp.Current.targets         $(_PlatformFolder)\Platform.targets             $(VCTargetsPath)\Microsoft.Cpp.Platform.targets                 $(_PlatformFolder)\ImportBefore\*。目标                 $(_PlatformFolder)\PlatformToolsets\$(PlatformToolset)\Toolset.target                 $(_PlatformFolder)\ImportAfter\*。目标

如果需要为工具集定义一些默认属性，可以将文件添加到相应的 ImportBefore 和 ImportAfter 文件夹。

使用此工具集时，Toolset.props 和 Toolset.targets 文件可以完全控制生成过程中发生的情况。 它们还可以控制可用的调试器、某些 IDE 用户界面，例如“ 属性页 ”对话框中的内容，以及项目行为的其他一些方面。

尽管工具集可以覆盖整个生成过程，但通常你只需要工具集来修改或添加一些生成步骤，或者将不同的生成工具用作现有生成过程的一部分。 为了实现此目标，工具集可以导入的一些常见属性和目标文件。 根据你希望工具集执行的操作，这些文件可用于用作导入或示例：

$(VCTargetsPath)\Microsoft.CppCommon.targets

此文件定义本机生成过程的主要部分，并导入：

$(VCTargetsPath)\Microsoft.CppBuild.targets

$(VCTargetsPath)\Microsoft.BuildSteps.targets

$(MSBuildToolsPath)\Microsoft.Common.Targets

$(VCTargetsPath)\Microsoft.Cpp.Common.props

设置使用 Microsoft 编译器和目标 Windows 的工具集的默认值。

$(VCTargetsPath)\Microsoft.Cpp.WindowsSDK.props

此文件确定 Windows SDK 位置，并为面向 Windows 的应用定义一些重要属性。

默认 C++ 生成过程在 Microsoft.CppCommon.targets 中定义。 目标没有调用任何特定的生成工具;它们指定主要生成步骤及其顺序和依赖项。

C++ 生成有三个主要步骤，这些步骤由以下目标表示：

BuildGenerateSources

BuildCompile

BuildLink

由于每个生成步骤都可以独立执行，因此在一个步骤中运行的目标不能依赖于作为不同步骤的一部分运行的目标中定义的项组和属性。 此划分允许某些生成性能优化。 尽管默认情况下未使用，但仍鼓励你遵守这种分离。

在每个步骤中运行的目标由以下属性控制：

$(BuildGenerateSourcesTargets)

$(BuildCompileTargets)

$(BeforeBuildLinkTargets)

每个步骤还有 Before 和 After 属性。

有关每个步骤中包含的目标示例，请参阅 Microsoft.CppBuild.targets 文件：

如果你查看目标，例如 _ClCompile，你将看到它们本身不直接执行任何操作，而是依赖于其他目标，包括 ClCompile：

ClCompile 和其他特定于生成工具的目标在 Microsoft.CppBuild.targets 中定义为空目标：

ClCompile由于目标为空，除非工具集重写目标，否则不会执行真正的生成操作。 工具集目标可以重写ClCompile目标，即导入 Microsoft.CppBuild.targets 后可以包含另一个ClCompile定义：

尽管在 Visual Studio 实现跨平台支持之前创建了名称， ClCompile 但目标不必调用CL.exe。 它还可以使用相应的 MSBuild 任务调用 Clang、gcc 或其他编译器。

目标 ClCompile 不应有任何依赖项，但 SelectClCompile 目标除外，单个文件编译命令需要在 IDE 中工作。

若要调用实际的生成工具，目标需要调用 MSBuild 任务。 有一个基本的 Exec 任务 ，可用于指定要运行的命令行。 但是，生成工具通常有许多选项，输入。 用于跟踪增量生成的输出，因此为它们执行特殊任务更有意义。 例如，该任务会将 CL MSBuild 属性转换为CL.exe开关，将其写入响应文件中，并调用CL.exe。 它还跟踪所有输入和输出文件，以便进行后续增量生成。 有关详细信息，请参阅 增量生成和最新检查。

Microsoft.Cpp.Common.Tasks.dll实现以下任务：

BSCMake

CL

ClangCompile (clang-gcc 开关)

LIB

LINK

MIDL

Mt

RC

XDCMake

CustomBuild (，如 Exec，但具有输入和输出跟踪)

SetEnv

GetOutOfDateItems

如果你有一个工具执行与现有工具相同的操作，并且具有与 clang-cl 和 CL 类似的命令行开关 (执行) ，则可以对这两个工具使用相同的任务。

如果需要为生成工具创建新任务，可以从以下选项中进行选择：

如果很少使用此任务，或者几秒钟对生成无关紧要，则可以使用 MSBuild“内联”任务：

xaml 任务 (自定义生成规则)

有关 Xaml 任务声明的一个示例，请参阅 $(VCTargetsPath)\BuildCustomizations\masm.xml及其用法，请参阅 $(VCTargetsPath)\BuildCustomizations\masm.targets。

代码任务

如果需要更好的任务性能或只需要更复杂的功能，请使用常规 MSBuild 任务写入 过程。

如果工具命令行上未列出该工具的所有输入和输出，如CLMIDLRC以下情况所示，并且需要自动输入和输出文件跟踪和 .tlog 文件创建，请从Microsoft.Build.CPPTasks.TrackedVCToolTask类派生任务。 目前，虽然基本 ToolTask 类有文档，但没有有关该类的详细信息 TrackedVCToolTask 的示例或文档。 如果这是特别感兴趣的，请在开发者社区上将语音添加到请求。

默认 MSBuild 增量生成目标使用 Inputs 和 Outputs 属性。 如果指定它们，则 MSBuild 仅当任何输入具有比所有输出都新的时间戳时，才会调用目标。 由于源文件通常包括或导入其他文件，并且生成工具会根据工具选项生成不同的输出，因此很难在 MSBuild 目标中指定所有可能的输入和输出。

为了管理此问题，C++ 生成使用不同的技术来支持增量生成。 大多数目标不指定输入和输出，因此，始终在生成期间运行。 目标调用的任务会将有关所有输入和输出的信息写入具有 .tlog 扩展名的 tlog 文件中。 稍后的版本使用 .tlog 文件来检查已更改的内容，需要重新生成哪些文件，以及最新版本。 .tlog 文件也是 IDE 中默认生成最新检查的唯一源。

若要确定所有输入和输出，本机工具任务使用 MSBuild 提供的 tracker.exe 和 FileTracker 类。

Microsoft.Build.CPPTasks.Common.dll定义 TrackedVCToolTask 公共抽象基类。 大多数本机工具任务派生自此类。

从 Visual Studio 2017 update 15.8 开始，可以使用 GetOutOfDateItems Microsoft.Cpp.Common.Tasks.dll中实现的任务为具有已知输入和输出的自定义目标生成 .tlog 文件。 或者，可以使用任务创建它们 WriteLinesToFile 。 例如，_WriteMasmTlogs请参阅 BuildCustomizations\masm.targets 中的$(VCTargetsPath)\目标。

有三种类型的 .tlog 文件： 读取、 写入和 命令行。 读取和写入 .tlog 文件由增量生成和 IDE 中的最新检查使用。 命令行 .tlog 文件仅在增量生成中使用。

MSBuild 提供以下帮助程序类来读取和写入 .tlog 文件：

CanonicalTrackedInputFiles

CanonicalTrackedOutputFiles

FlatTrackingData 类可用于访问读取和写入 .tlog 文件，并标识比输出更新的输入，或者如果缺少输出。 它在最新的检查中使用。

命令行 .tlog 文件包含有关生成中使用的命令行的信息。 它们仅用于增量生成，而不是最新的检查，因此内部格式由生成它们的 MSBuild 任务确定。

读取 .tlog 文件 (*.read.*.tlog) 包含有关源文件及其依赖项的信息。

行开头的插入符号 (^) 指示一个或多个源。 共享相同依赖项的源由垂直条分隔 (|) 。

依赖项文件列在源之后，每个文件都位于其自己的行中。 所有文件名都是完整路径。

例如，假设项目源位于 F：\test\ConsoleApplication1\ConsoleApplication1 中。 如果源文件 Class1.cpp 包含以下内容：

然后 CL.read.1.tlog 文件包含源文件，后跟其两个依赖项：

不需要以大写形式编写文件名，但对于某些工具来说，这是一种便利。

编写 .tlog (*.write.*.tlog) 文件连接源和输出。

行开头的插入符号 (^) 指示一个或多个源。 多个源由垂直条分隔 () | 。

从源生成的输出文件应列在源之后，每个文件都位于自己的行中。 所有文件名都必须是完整路径。

例如，对于具有附加源文件 Class1.cpp 的简单 ConsoleApplication 项目， link.write.1.tlog 文件可能包含：

在 IDE 中，.vcxproj 项目使用一组 MSBuild 目标从项目获取其他信息并重新生成输出文件。 其中一些目标仅用于设计时生成，但其中许多目标用于常规生成和设计时生成。

有关设计时生成的常规信息，请参阅 设计时生成的 CPS 文档。 本文档仅部分适用于 Visual C++ 项目。

设计 CompileDesignTime 时生成文档中提到的和 Compile 目标永远不会针对 .vcxproj 项目运行。 Visual C++ .vcxproj 项目使用不同的设计时目标来获取 IntelliSense 信息。

.vcxproj 项目中使用的设计时目标在 Microsoft.Cpp.DesignTime.targets 中$(VCTargetsPath)\定义。

目标 GetClCommandLines 收集 IntelliSense 的编译器选项：

DesignTimeBuildInitTargets – 仅设计时目标，设计时生成初始化是必需的。 除此之外，这些目标禁用某些常规生成功能以提高性能。

ComputeCompileInputsTargets – 一组用于修改编译器选项和项的目标。 这些目标在设计时和常规生成中运行。

目标调用 CLCommandLine 任务以创建用于 IntelliSense 的命令行。 同样，尽管它的名称，但它不仅可以处理 CL 选项，还可以处理 Clang 和 gcc 选项。 编译器开关的类型由 ClangMode 属性控制。

目前，任务生成的 CLCommandLine 命令行始终使用 CL 开关 (，即使在 Clang 模式下) ，因为它们更易于 IntelliSense 引擎分析。

如果要添加在编译之前运行的目标，无论是常规版本还是设计时，请确保它不会中断设计时生成或影响性能。 测试目标的最简单方法是打开开发人员命令提示符并运行以下命令：

此命令生成一个详细的生成日志 msbuild.log，该日志在末尾具有目标和任务的性能摘要。

请确保在所有 Condition ="'$(DesignTimeBuild)' != 'true'" 操作中使用，这些操作仅适用于常规生成，而不适用于设计时生成。

默认情况下，对于桌面本机项目，此功能处于禁用状态，缓存项目当前不支持此功能。

如果 GeneratorTarget 为项目项定义了元数据，则当加载项目和更改源文件时，目标会自动运行。

例如，若要从 .xaml 文件自动生成 .cpp 或 .h 文件， $(VSInstallDir)\MSBuild\Microsoft\WindowsXaml\v16.0\*\Microsoft.Windows.UI.Xaml.CPP.Targets 文件定义以下实体：

若要用于 Task.HostObject 获取源文件的未保存内容，目标和任务应注册为 pkgdef 中给定项目的 MsbuildHostObjects ：

Visual C++ 项目系统基于 VS 项目系统，并使用其扩展点。 但是，项目层次结构实现特定于 Visual C++ 而不是基于 CPS，因此层次结构扩展性仅限于项目项。

有关常规设计信息，请参阅 VC++ 项目的框架多目标。

简单来说，在 C++ 项目的 “项目属性 ”对话框中看到的属性页由 规则 文件定义。 规则文件指定要在属性页上显示的属性集，以及它们应保存在项目文件中的方式和位置。 规则文件.xml使用 Xaml 格式的文件。 用于序列化它们的类型在 Microsoft.Build.Framework.XamlTypes 中介绍。 有关项目中规则文件使用的详细信息，请参阅 属性页 XML 规则文件。

必须将规则文件添加到 PropertyPageSchema 项组：

Context 元数据限制规则可见性，该可见性也受规则类型控制，并且可以具有以下值之一：

Project | File | PropertySheet

CPS 支持上下文类型的其他值，但它们不在 Visual C++ 项目中使用。

如果规则应在多个上下文中可见，请使用分号 (;) 分隔上下文值，如下所示：

规则格式非常简单，因此本部分仅描述影响规则在用户界面中外观的属性。

该 PageTemplate 属性定义规则在 “属性页 ”对话框中的显示方式。 该属性可以具有以下值之一：

示例： $(VCTargetsPath)\1033\general.xml

示例： $(VCTargetsPath)\1033\clang.xml

示例： $(VCTargetsPath)\1033\debugger_local_windows.xml

示例： $(VCTargetsPath)\1033\userMacros.xml

如果规则使用基于属性网格的模板之一，则可以将这些扩展点用于其属性：

属性值编辑器

动态枚举值提供程序

如果要使用现有规则，但需要添加或删除 (（即隐藏) 几个属性）可以创建 扩展规则。

也许你希望工具集使用大部分项目默认规则，但只替换其中一个或多个规则。 例如，假设只想更改 C/C++ 规则以显示不同的编译器开关。 可以提供与现有规则相同的名称和显示名称的新规则，并在导入默认 cpp 目标后将其 PropertyPageSchema 包含在项组中。 项目中只使用具有给定名称的一个规则，最后一个规则包含在 PropertyPageSchema 项目组中。

ProjectItemsSchema.xml文件定义ContentType被视为项目项的项的和ItemType值，并定义FileExtension元素以确定将新文件添加到哪个项组。

默认 ProjectItemsSchema 文件位于 1033\ProjectItemsSchema.xml中$(VCTargetsPath)\。 若要扩展它，必须创建具有新名称的架构文件，例如 MyProjectItemsSchema.xml：

然后在目标文件中，添加：

示例： $(VCTargetsPath)\BuildCustomizations\masm.xml

Visual Studio 中的调试服务支持调试引擎的扩展性。 有关详细信息，请参阅以下示例：

MIEngine，开放源代码支持 lldb 调试的项目

Visual Studio 调试引擎示例

若要指定调试会话的调试引擎和其他属性，必须实现 调试启动器 MEF 组件，并添加 debugger 规则。 有关示例，请参阅 $(VCTargetsPath)\1033\debugger_local_windows.xml文件。

.vcxproj 项目使用 Visual Studio Project System 扩展性来 部署提供程序。

默认情况下，生成最新检查需要读取 .tlog 并在生成期间在所有生成输入和输出的文件夹中创建 $(TlogLocation) .tlog 文件。

若要使用自定义最新检查，请使用：

通过在 Toolset.targets 文件中添加NoVCDefaultBuildUpToDateCheckProvider功能来禁用默认的最新检查：

实现自己的 IBuildUpToDateCheckProvider。

默认的 .vcxproj 项目升级程序将更改 PlatformToolsetMSBuild ApplicationTypeRevision工具集版本和.NET Framework。 最后两个始终更改为 Visual Studio 版本默认值，但PlatformToolsetApplicationTypeRevision可由特殊 MSBuild 属性控制。

升级程序使用这些条件来确定是否可以升级项目：

对于定义 ApplicationType 项目， ApplicationTypeRevision并且有一个文件夹的修订号高于当前修订号。

该属性 _UpgradePlatformToolsetFor_ 为当前工具集定义，其值不等于当前工具集。

在这些属性名称中， 表示工具集名称，其中包含由下划线 (_) 替换的所有非字母数字字符。

升级项目后，它将参与 解决方案重定向。 有关详细信息，请参阅 IVsTrackProjectRetargeting2。

如果要在项目使用特定工具集时在解决方案资源管理器中装饰项目名称，请定义属性_PlatformToolsetShortNameFor_。

有关属性_PlatformToolsetShortNameFor_定义的示例_UpgradePlatformToolsetFor_，请参阅 Microsoft.Cpp.Default.props 文件。 有关用法示例，请参阅 $(VCTargetPath)\Microsoft.Cpp.Platform.targets 文件。

若要使用自定义项目升级程序对象，请实现 MEF 组件，如下所示：

代码可以导入并调用默认的 .vcxproj 升级程序对象：

IProjectRetargetHandler 在 Microsoft.VisualStudio.ProjectSystem.VS.dll 中定义，类似于 IVsRetargetProjectAsync。

定义属性 VCProjectUpgraderObjectName 以告知项目系统使用自定义升级程序对象：

若要禁用项目升级，请使用值 NoUpgrade ：

为了提高在 Visual Studio 2017 中使用大型 C++ 解决方案时的性能，引入了 项目缓存 。 它作为填充项目数据的 SQLite 数据库实现，然后用于加载项目，而无需将 MSBuild 或 CPS 项目加载到内存中。

由于缓存中加载的 .vcxproj 项目没有 CPS 对象，因此无法创建导入 UnconfiguredProject 或 ConfiguredProject 无法创建的扩展的 MEF 组件。 为了支持扩展性，Visual Studio 检测到项目是使用 (还是可能) MEF 扩展时，不会使用项目缓存。

这些项目类型始终完全加载，并且内存中具有 CPS 对象，因此会为其创建所有 MEF 扩展：

启动项目

具有自定义项目升级程序的项目，即定义 VCProjectUpgraderObjectName 属性

不面向桌面 Windows 的项目，即定义属性ApplicationType

共享项项目 (.vcxitems) ，以及通过导入 .vcxitems 项目引用这些项目的任何项目。

如果未检测到这些条件，则会创建项目缓存。 缓存包含 MSBuild 项目的所有数据，这些数据需要回答 get 接口上的 VCProjectEngine 查询。 这意味着，扩展完成的 MSBuild 属性和目标文件级别的所有修改都应在从缓存加载的项目中工作。

有关如何创建 VSIX 文件的信息，请参阅 Shipping Visual Studio Extensions。 有关如何将文件添加到特殊安装位置的信息，例如，若要在下方 $(VCTargetsPath)添加文件，请参阅 扩展文件夹外部的安装。

Microsoft 生成系统 (MSBuild) 为项目文件提供生成引擎和基于 XML 的可扩展格式。 你应该熟悉基本的 MSBuild 概念 以及 MSBuild for Visual C++ 的工作原理，以便扩展 Visual C++ 项目系统。

Managed Extensibility Framework (MEF) 提供 CPS 和 Visual C++ 项目系统使用的扩展 API。 有关 CPS 如何使用 MEF 的概述，请参阅 VSProjectSystem MEF 中的 CPS 和 MEF。

可以自定义现有生成系统以添加生成步骤或新的文件类型。 有关详细信息，请参阅 MSBuild (Visual C++) 概述 和 处理项目属性。