自定义生成

  • 项目

使用标准生成进程（导入 Microsoft.Common.props 和 Microsoft.Common.targets）的 MSBuild 项目有多个可用于自定义生成过程的扩展性挂钩 。

许多可自定义的生成操作由属性控制。 了解如何以及在何处设置属性值以获得所需的效果非常重要。 可以在命令行（和响应文件）、特殊文件（如 Directory.Build.props）、导入的文件或项目文件中设置属性。 了解属性的使用、设置或更改位置以及导入文件的顺序（包括从诸如 .NET SDK 之类的 SDK 隐式导入）非常重要。

有关属性的列表，请参阅 MSBuild 通用属性。

探索自定义选项

以下自定义选项按复杂性和影响范围的增加的顺序列出。 我们建议使用最不复杂的自定义选项，从此列表的顶部开始，以满足你的目的。

自定义选项 说明
将参数添加到 MSBuild 命令行 设置影响主项目生成和所有依赖项目的生成的全局属性。
自定义单个项目的生成 将属性添加到 .props 或 .targets 文件以自定义生成设置。
处理生成过程中生成的文件 如何确保生成的文件正确包含在生成输出中。
自定义一个或多个项目的生成 将属性添加到 Directory.Build.props 或将属性和目标添加到 Directory.Build.targets，以自定义文件夹下所有项目的生成。 此方法可用于设置 SDK 设置或使用的属性，以及确定自定义项的范围，以便它们影响文件夹或子文件夹中的所有项目。
自定义本地生成 仅在本地计算机上更改生成，而不影响共享的源文件。
自定义所有 .NET 生成 为 .NET 生成自定义具有系统范围的生成。
自定义 C++ 生成 自定义 C++ 生成，其范围限定为项目、解决方案、文件夹或由系统上的 MSBuild 安装管理的所有生成。

向项目的命令行 MSBuild 调用添加参数

可以在命令行上设置全局属性。 全局属性影响所有项目生成，包括依赖项。 回想一下，生成项目会自动触发所有项目依赖项的可能生成。 MSBuild 的正常行为是生成任何过期的依赖项目。 这些依赖项目生成使用与原始项目相同的命令行全局属性设置启动。

源目录中或之上的 Directory.Build.rsp 文件会应用到项目的命令行生成。 有关详细信息，请参阅 MSBuild 响应文件。

选择将属性添加到 .props 或 .targets 文件

MSBuild 依赖于导入顺序，属性（或 UsingTask 或目标）的最后一个定义是使用的定义。

使用显式导入时，可以随时从 .props 或 .targets 文件导入。 下面介绍广泛使用的约定：

  • .props 文件在导入顺序的早期导入。

  • .targets 文件在生成顺序的后期导入。

此约定由 <Project Sdk="SdkName"> 导入强制执行（即，在文件的所有内容之前首先导入 Sdk.props，然后在文件的所有内容之后最后导入 Sdk.targets）。

在决定在何处放置属性后，使用以下通用原则：

  • 对于许多属性，在何处定义它们并不重要，因为它们不会被覆盖，只能在执行时读取。

  • 对于可能在单个项目中自定义的行为，请在 .props 文件中设置默认值。

  • 通过读取可能自定义属性的值，避免在 .props 文件中设置依赖属性，因为在 MSBuild 读取用户项目之前不会进行自定义。

  • 在 .targets 文件中设置依赖属性，因为它们将从单个项目中提取自定义项。

  • 如果需要覆盖属性，请在所有用户项目自定义项生效后，在 .targets 文件中执行此操作。 使用派生属性时务必小心；还可能需要覆盖派生属性。

  • 包括 .props 文件中的项目（以属性为条件）。 在任何项目之前都要考虑所有属性，因此可以提取用户项目属性自定义项，在 .props 文件中添加导入的项使用户的项目有机会 Remove 或 Update 导入所引入的任何项目。

  • 定义 .targets 文件中的目标。 但是，如果 SDK 导入了 .targets 文件，请记住此方案使得覆盖目标更加困难，因为默认情况下用户的项目没有可以覆盖它的地方。

  • 如果可能，宁可在评估时自定义属性，也不更改目标内的属性。 此原则可以更轻松地加载项目并了解正在执行的操作。

相关内容