PackageReference 项目文件中

包引用（使用 <PackageReference> MSBuild 项）直接在项目文件中指定 NuGet 包依赖项，而不是具有单独的 packages.config 文件。 使用 PackageReference 不会影响 NuGet 的其他方面;例如，文件（包括包源）中的 NuGet.Config 设置仍按 Common NuGet 配置中所述应用。

借助 PackageReference，还可以使用 MSBuild 条件来选择每个目标框架的包引用或其他分组。 它还允许对依赖项和内容流进行精细控制。 （有关详细信息，请参阅 NuGet 包并还原为 MSBuild 目标。）

项目类型支持

默认情况下，PackageReference 用于 .NET 项目、.NET Standard 项目和面向 Windows 10 内部版本 15063（创意者更新）及更高版本的 UWP 项目，但C++ UWP 项目除外。 .NET Framework 项目支持 PackageReference，但目前默认为 packages.config。 若要在 .NET Framework 项目中使用 PackageReference，请将依赖项从项目文件packages.config项目文件中，然后删除 packages.config。

ASP.NET 面向完整 .NET Framework 的应用仅包含对 PackageReference 的有限支持 。 不支持C++和 JavaScript 项目类型。

添加 PackageReference

使用以下语法在项目文件中添加依赖项：

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

控制依赖版本

指定包版本的约定与使用 packages.config时相同：

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

在上面的示例中，3.6.0 表示 >任何版本 =3.6.0 且优先于最低版本，如 包版本控制中所述。

对没有包依赖项的项目使用 PackageReference

高级：如果项目中未安装任何包（项目文件中没有 PackageReferences 且没有 packages.config 文件），但希望将项目还原为 PackageReference 样式，则可以在项目文件中将 Project 属性 RestoreProjectStyle 设置为 PackageReference。

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

如果引用了 PackageReference 样式的项目（现有 csproj 或 SDK 样式项目），这可能很有用。 这样，您项目中引用的包将能够通过可传递的方式被引用。

PackageReference 和源

在 PackageReference 项目中，依赖项版本将在还原时自动解析。 因此，在 PackageReference 项目中，所有源都需要可用于所有还原。

浮动版本

支持浮动版本PackageReference：

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
    <!-- ... -->
</ItemGroup>

控制依赖项资产

你可能纯粹使用依赖项作为开发工具，并且可能不希望向将使用包的项目公开该依赖项。 在此方案中，可以使用 PrivateAssets 元数据来控制此行为。

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

以下元数据标记控制依赖项资产：

这些标记的允许值如下所示，多个值用分号分隔，但allnone必须单独显示这些值：

<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

请注意，由于 build 不包含 PrivateAssets在内，目标和属性 将 流向父项目。 例如，请考虑在生成名为 AppLogger 的 NuGet 包的项目中使用上述引用。 AppLogger 可以使用来自 Contoso.Utility.UsefulStuff 的目标和属性，使用 AppLogger 的项目也同样可以。

添加 PackageReference 条件

可以使用条件来控制是否包含包。 条件可以使用目标或 props 文件中定义的任何 MSBuild 变量或变量。 但是，目前仅支持 TargetFramework 变量。

例如，假设你 netstandard1.4 面向的是目标 net452 ，但具有仅适用于 net452的依赖项。 在这种情况下，你不希望 netstandard1.4 使用包的项目添加不必要的依赖项。 若要防止出现这种情况，请按如下所示指定条件 PackageReference ：

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

使用此项目构建的包将表明，Newtonsoft.Json 仅作为 net452 目标的依赖项被包含在内。

还可以在 ItemGroup 级别应用条件，并应用于所有子 PackageReference 元素：

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

此功能适用于 NuGet 5.0 或更高版本以及 Visual Studio 2019 16.0 或更高版本。

有时，需要从 MSBuild 目标引用包中的文件。 在 packages.config 基于项目中，包安装在相对于项目文件的文件夹中。 但在 PackageReference 中，包从全局包文件夹中使用，这可能因计算机而异。

为了弥合这一差距，NuGet 引入了一个属性，该属性指向用于使用软件包的位置。

Example:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

此外，NuGet 会自动为包含工具文件夹的包生成属性。

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

MSBuild 属性和包标识没有相同的限制，因此包标识需要更改为 MSBuild 友好名称，以单词 Pkg为前缀。 若要验证生成的属性的确切名称，请查看生成的 nuget.g.props 文件。

PackageReference 别名

在某些罕见情况下，不同的包将包含同一命名空间中的类。 从 NuGet 5.7 和 Visual Studio 2019 Update 7 开始，与 ProjectReference 等效，PackageReference 支持 Aliases。 默认情况下，不提供别名。 指定别名时，需要使用别名引用来自批注包 的所有 程序集。

可以在 NuGet\Samples 中查看示例使用情况。

在项目文件中，按如下所示指定别名：

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

在代码中，按如下所示使用它：

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

NuGet 警告和错误

此功能适用于 NuGet 4.3 或更高版本以及 Visual Studio 2017 15.3 或更高版本。

对于许多打包和还原方案，所有 NuGet 警告和错误都有代码，并以 NU**** 开始。 参考文档中列出了所有 NuGet 警告和错误。

NuGet 观察以下警告属性：

• TreatWarningsAsErrors，将所有警告视为错误。
• WarningsAsErrors，将特定警告视为错误。
• NoWarn，隐藏项目范围或包范围的特定警告。

Examples:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

禁止显示 NuGet 警告

尽管建议在打包和还原操作期间解决所有 NuGet 警告，但在某些情况下，忽略它们是合适的。 若要在整个项目中抑制警告，请考虑执行以下操作：

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

有时警告仅适用于图形中的特定包。 可以选择通过在 PackageReference 项上添加警告 NoWarn 来更有选择地取消该警告。

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

在 Visual Studio 中取消 NuGet 包警告

在 Visual Studio 中时，还可以 通过 IDE 取消警告 。

锁定依赖项

此功能适用于 NuGet 4.9 或更高版本以及 Visual Studio 2017 15.9 或更高版本。

NuGet 还原的输入是项目文件（顶级或直接依赖项）中的 PackageReference 一组项，输出是所有包依赖项（包括可传递依赖项）的完整关闭。 如果输入的 PackageReference 列表未更改，NuGet 将尝试始终生成包依赖项的完整闭包。 ** 但是，在某些情况下，它无法做到这一点。 例如：

• 使用浮点式版本时，如 <PackageReference Include="My.Sample.Lib" Version="4.*"/>. 虽然此处的意图是在每次还原包时浮动到最新版本，但在某些情况下，用户要求将图形锁定到特定最新版本，并在显式手势下浮动到更高版本（ 如果可用）。

• 一个符合 PackageReference 版本要求的较新版本包已发布。 例如：

  • 第 1 天：如果已指定 <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> ，但 NuGet 存储库上可用的版本为 4.1.0、4.2.0 和 4.3.0。 在这种情况下，NuGet 将解析为 4.1.0（最接近的最低版本）。

  • 第 2 天：版本 4.0.0 发布。 NuGet 现在将找到完全匹配项，并开始解析为 4.0.0。

• 从存储库中删除给定的包版本。 尽管 nuget.org 不允许删除包，但并非所有包存储库都具有此约束。 这会导致 NuGet 在无法解析为已删除的版本时找到最佳匹配项。

启用锁定文件

若要持久保存包依赖项的完整关闭，可以通过为项目设置 MSBuild 属性 RestorePackagesWithLockFile 来选择加入锁定文件功能：

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

如果设置了此属性，NuGet 还原将在列出所有包依赖项的项目根目录中生成锁定文件（packages.lock.json）。

restore 具有锁文件的行为

如果项目存在锁文件，则 NuGet 使用此锁文件运行 restore。 NuGet 会快速检查包依赖项中是否有任何更改，如项目文件（或依赖项目的文件）中所述，如果没有更改，它只会还原锁定文件中提到的包。 包依赖项没有重新评估。

如果 NuGet 检测到项目文件中所述的已定义依赖项的更改，它将重新评估包图并更新锁定文件以反映项目的新包关闭。

对于 CI/CD 和其他情境，在您不希望即时更改包依赖项时，可以通过将 lockedmode 设置为 true：

对于 dotnet.exe，请运行：

> dotnet.exe restore --locked-mode

对于 msbuild.exe，请运行：

> msbuild.exe -t:restore -p:RestoreLockedMode=true

还可以在项目文件中设置此条件 MSBuild 属性：

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

如果锁定模式为 true，还原将还原锁文件中列出的确切包，或者如果在创建锁定文件后更新了项目的已定义包依赖项，则还原将失败。

锁定文件和 PrunePackageReference

PrunePackageReference 通过删除不必要的可传递包来更改项目的依赖项。 删除这些包不应在运行时产生影响，但它会影响锁定文件。 如果为现有项目启用修剪，每次锁定文件重新生成时，它可能会导致包数量少于重新生成之前。 锁定文件的最新状态检查是修剪感知的，这意味着如果您在项目中启用了修剪，检查将会考虑被修剪的包。 但是，下次重新生成锁文件时，它将移除已修剪的包，因此你可能会看到异常大的差异。

将锁定文件设置为源存储库的一部分

如果要生成应用程序、可执行文件和相关项目位于依赖项链的开头，请签入到源代码存储库的锁定文件，以便 NuGet 可以在还原期间使用它。

但是，如果你的项目是未交付的库项目或其他项目所依赖的常见代码项目， 则不应 签入锁定文件作为源代码的一部分。 在还原/生成依赖于此通用代码项目的项目的还原/生成过程中，不能使用通用代码项目的锁定包依赖项（如锁定文件中所列），这不会造成任何损害。

Example:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

如果ProjectA依赖于版本PackageX，并且还引用依赖于版本2.0.0的ProjectB，那么PackageX的锁定文件将列出对1.0.0版本的ProjectB依赖项。 但是，在构建 ProjectA 时，其锁文件将包含对 PackageX 版本 2.0.0 的依赖项，而不是如 的锁定文件中所列的版本 1.0.0。 因此，对于依赖于通用代码项目的项目来说，该项目的锁定文件对其所解决的包的控制几乎微乎其微。

锁定文件扩展性

可以使用锁定文件控制各种还原行为，如下所示：

NuGet 依赖项解析程序

NuGet 依赖项解析程序遵循 依赖项解析文档中所述的四个规则。

为了提高还原作的性能和可伸缩性，还原算法是在 6.12 版本中重写的。 从 6.12 版起，默认情况下为所有 PackageReference 项目启用新的还原算法。 虽然新的还原算法在功能上等同于上一个算法，但与任何软件一样，可能会有 bug。 若要还原到以前的实现，请将 MSBuild 属性 RestoreUseLegacyDependencyResolver 设置为 true。

如果你在 6.12、.NET 9 或 17.12 中遇到还原失败（在早期版本中未重现），请在 GitHub 上提出问题。 旧算法和新算法之间的任何差异都可能产生不同的影响，例如在编译期间或运行时。 还有一种可能性是更改不会导致故障，而是会还原不同的包版本。 如果认为可能受到任何更改的影响，可以执行以下步骤来验证 NuGet 还原算法中的更改是否是根本原因。

还原操作会将结果写入 MSBuildProjectExtensionsPath 目录，然后与新旧算法进行比较以查找差异。 通常，这是 obj 构建的文件夹。 可以使用 msbuild.exe 或 dotnet.exe 执行后续步骤。

1. 删除项目的obj文件夹。

2. 运行 msbuild -t:restore

3. 将obj的内容保存到一个位置以指示它的new行为。

4. 运行 msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"。

5. 将obj的内容保存到一个位置以指示它的legacy行为。

6. 比较两个目录中的文件，尤其是 project.assets.json。

   可以突出显示差异的工具特别有用（例如，在 Visual Studio Code 中打开这两个文件，并使用右键单击“选择比较”和“比较所选”）。

如果遵循上述方法，则 project.assets.json 文件之间确有 1 个差异：

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

如果存在更多差异，请在 GitHub 上提交包含 所有详细信息的问题。

AssetTargetFallback

该 AssetTargetFallback 属性允许你为项目引用的项目和项目使用的 NuGet 包指定其他兼容的框架版本。

如果使用指定包依赖项 PackageReference ，但该包不包含与项目的目标框架兼容的资产，该 AssetTargetFallback 属性将发挥作用。 使用 AssetTargetFallback 中指定的每个目标框架重新检查引用包的兼容性。 通过project引用package或AssetTargetFallback时，将引发NU1701警告。

有关如何影响 AssetTargetFallback 兼容性的示例，请参阅下表。

可以使用 ; 作为分隔符来指定多个框架。 若要添加回退框架，可以执行以下操作：

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

如果你想覆盖现有的 $(AssetTargetFallback) 值，可以省略 AssetTargetFallback，而不是添加它。

PrunePackageReference

.NET 运行时不断发展，每个版本都有性能改进和新 API。 有时还会将添加到 .NET 的新功能作为包提供，以便使用较旧的目标框架的开发人员可以使用 System.Text.Json 等库。 这通常会导致在针对 System.Text.Json 8.0.0 或 .NET 9的项目中出现 .NET 8。 此依赖项是不必要的，生成冲突解决不会使用来自包的程序集，因为它已在 .NET 运行时中可用。 从 NuGet 版本 6.13 和 .NET SDK 9.0.200 开始， PrunePackageReference 可以在还原时对基于 .NET SDK 的项目对这些包进行修剪。 修剪的第一次迭代仅影响可传递包，但从 .NET SDK 10 开始，包修剪也会影响直接包。

包修剪作为 .NET 9 SDK 的选择加入功能提供，并且默认为面向 .NET 10 SDK 的项目 >= .NET 10.0 的所有框架启用。

包修剪仅适用于默认依赖项解析程序，如 6.12 中发布的。

PrunePackageReference 规范

要修剪的包列表是使用 PrunePackageReference 项定义的。

以下属性可用于修改修剪行为。

.NET SDK 预定义要为你修剪的包列表。

PrunePackageReference 的工作原理

在还原过程中指定要裁剪的包时，它将从依赖关系图中删除。 当包被修剪时，会显示一条消息（详细程度可见），指示已为给定的目标框架删除该包。

对于可传递包，这意味着其他包或项目的依赖项，包不会下载，也不会显示在 NuGet 的任何输出中。

对于直接包， PrivateAssets='all' 并 IncludeAssets='none' 隐式应用。

• IncludeAssets='none' 确保生成期间不会使用此包中的程序集。 在修剪出现之前，构建过程中进行的冲突解决确保了平台程序集优先于来自包的程序集。
• PrivateAssets='all' 确保这些软件包未被包含在其他软件包中或通过项目引用。

Example:

如下所示的项目：

  <PropertyGroup>
    <TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="9.0.4" />
  </ItemGroup>

将具有以下依赖项的 nuspec：

<dependencies>
    <group targetFramework=".NETFramework4.7.2">
        <dependency id="System.Text.Json" version="9.0.4" />
    </group>
    <group targetFramework="net9.0">
    </group>
</dependencies>

如果你的项目中可以完全删除某个直接的 PackageReference，并且项目的某个框架是 .NET 10 或更高版本，则会引发 NU1510 错误，要求你删除该包。 遵循此建议可降低项目图的复杂性。

下表汇总了所有包修剪行为。

PrunePackageReference 应用程序

包修剪的好处有两个方面：

• 性能优势，通过减少依赖项关系图中的包的数量
• 通过使用组件扫描程序（例如 NuGetAudit）减少误报

在审核设置为 <a0/a0> 的包时，修剪特别有价值。 如果使用的是 .NET 9，建议通过设置为 “RestoreEnablePackagePruningtrue删除” 来尝试修剪。