包中的 MSBuild .props 和 .targets

  • 项目

除更传统的程序集外，NuGet 包有时可能还会向使用该包的项目添加自定义生成目标或属性。 此操作可通过在项目的构建文件夹中添加有效的 MSBuild 文件来实现，格式为 <package_id>.targets 或 <package_id>.props（例如 Contoso.Utility.UsefulStuff.targets）。

生成文件夹

随着 NuGet 的演变，我们已为生成 .props 和 .targets 添加了各种不同的文件夹。

文件夹 NuGet 版本 使用
build 2.5+ 为项目的每个框架生成逻辑。
buildMultiTargeting 4.0+ 为以多个框架为目标的项目生成 outer build 逻辑。 仅限 PackageReference。
buildTransitive 5.0+ 为以可传递的方式流入任意使用项目的资产生成逻辑。 请参阅功能页。 仅限 PackageReference。

特定于框架的生成文件夹

所有 3 个生成文件夹都遵循相同的模式，根据项目目标框架决定最适合的文件。

项目根生成文件夹 build/<package_id>.targets 和 build/<package_id>.props 中的文件被视为适用于所有目标框架。

若要提供特定于框架的文件，首先将其放置到合适的子文件夹中，如下所示：

    \build
        \netstandard1.4
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets
        \net462
            \Contoso.Utility.UsefulStuff.props
            \Contoso.Utility.UsefulStuff.targets

最好在适合的时候使用特定于框架的生成文件夹，以避免在包可能不支持的项目中出现误报安装。

请注意，如果某个包在 lib 或 ref 文件夹中没有任何文件，并且只有特定于框架的生成文件夹下的文件，则该包将被视为与所有项目兼容。 包工具的最新版本在创建此类包时引发 NU5127 警告。

使用包含生成文件的包的项目

PackageReference 项目

不将 .props 和 .targets 添加到项目文件中，而是改为通过 {projectName}.nuget.g.targets 和 {projectName}.nuget.g.props 提供。 运行还原时会自动生成这些文件。

当项目以多个框架为目标时，导入到这些文件的条件取决于目标框架名称。

可将多个框架目标的 MSBuild .props 和 .targets 文件置于 \buildMultiTargeting 文件夹中。 生成导入后，将设置 MSBuild 属性 $(TargetFramework) 为空的条件。

packages.config项目

当 NuGet 使用 \build 文件安装包时，它在指向 .targets 和 .props 文件的项目文件中添加 MSBuild <Import> 元素。 （在项目文件的顶部添加 .props；在底部添加 .targets）。为每个目标框架添加单独的条件 MSBuild <Import> 元素。

使用 MSBuild 属性和目标创作包

可使用以下任一工具将 MSBuild .props 和 .targets 包包含在包中。

MSBuild 属性和目标的内容指南

NuGet 不会限制你创作 .props 和 .targets 的方式，因为它们会根据包作者和目标项目本身的需要而有所不同。

绝不能在包的 .props 和 .targets 中执行某些操作，例如不能指定影响还原的属性和项目，因为它们将被自动排除。

  • 不能添加或更新的属性示例包括：TargetFramework、TargetFrameworkMoniker、TargetPlatformMoniker、AssetTargetFallback 等。

  • 不能添加或更新的项的示例包括：PackageReference、PackageVersion、PackageDownload 等。