将 NuGet pack 和 restore 用作 MSBuild 目标

项目
11/09/2023

NuGet 4.0 及以上版本

通过使用 PackageReference 格式，NuGet 4.0 及以上版本可将所有清单元数据直接存储在项目文件中，而不是使用单独的 .nuspec 文件。

如下所述，对于 MSBuild 15.1 及以上版本，NuGet 还是具有 pack 和 restore 目标的一等 MSBuild 公民。借助这些目标，你可以像使用任何其他 MSBuild 任务或目标一样使用 NuGet。有关创建使用 MSBuild 的 NuGet 包的说明，请参阅创建使用 MSBuild 的 NuGet 包。（对于 NuGet 3.x 及先前版本，可通过 NuGet CLI 使用 pack 和 restore 命令。）

目标生成顺序

由于 pack 和 restore 均为 MSBuild 目标，因此可访问它们以增强工作流。例如，假设希望在打包后将包复制到网络共享。此操作可通过向项目文件中添加以下内容来完成：

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

同样，你可以编写 MSBuild 任务、编写自己的目标并在 MSBuild 任务中使用 NuGet 属性。

注意

$(OutputPath) 为相对路径，且需从项目根目录运行此命令。

包目标

对于使用 PackageReference 格式的 .NET 项目，使用 msbuild -t:pack 会从项目文件获取输入以用于创建 NuGet 包。

下表描述了可添加到第一个 <PropertyGroup> 节点中的项目文件的 MSBuild 属性。在 Visual Studio 2017 及更高版本中，通过右键单击项目并选择上下文菜单上的“编辑 {project_name}”，即可轻松进行这些编辑。为方便起见，此表由 .nuspec 文件中的等效属性进行组织。

注意

MSBuild 不支持 .nuspec 中的 Owners 和 Summary 属性。

属性/nuspec 值	MSBuild 属性	默认	备注
`Id`	`PackageId`	`$(AssemblyName)`	`$(AssemblyName)` 来自 MSBuild
`Version`	`PackageVersion`	版本	它与 semver 兼容，例如`1.0.0`、`1.0.0-beta` 或 `1.0.0-beta-00345`。如果未设置，则默认为 `Version`。
`VersionPrefix`	`VersionPrefix`	empty	设置 `PackageVersion` 会覆盖 `VersionPrefix`
`VersionSuffix`	`VersionSuffix`	empty	设置 `PackageVersion` 会覆盖 `VersionSuffix`
`Authors`	`Authors`	当前用户的用户名	用分号分隔的包作者的列表，这些作者与 nuget.org 上的配置文件名称匹配。这些内容会显示在 nuget.org 的 NuGet 库中，且由同一作者用于交叉引用包。
`Owners`	空值	不在 nuspec 中
`Title`	`Title`	`$(PackageId)`	明了易用的包标题，通常用在 UI 显示中，如 nuget.org 上和 Visual Studio 中包管理器上的那样。
`Description`	`Description`	“包描述”	程序集的详细说明。如果未指定 `PackageDescription`，则此属性还可用作包的说明。
`Copyright`	`Copyright`	empty	包的版权详细信息。
`RequireLicenseAcceptance`	`PackageRequireLicenseAcceptance`	`false`	一个布尔值，指定客户端是否必须提示使用者接受包许可证后才可安装包。
`license`	`PackageLicenseExpression`	empty	对应到 `<license type="expression">`。请参阅打包许可证表达式或许可证文件。
`license`	`PackageLicenseFile`	empty	如果使用的是自定义许可证或是没有分配 SPDX 标识符的许可证，则为包中许可证文件的路径。需显式打包引用的许可证文件。对应到 `<license type="file">`。请参阅打包许可证表达式或许可证文件。
`LicenseUrl`	`PackageLicenseUrl`	empty	`PackageLicenseUrl` 已弃用。请改用 `PackageLicenseExpression` 或 `PackageLicenseFile`。
`ProjectUrl`	`PackageProjectUrl`	empty
`Icon`	`PackageIcon`	empty	包中要用作包图标的图像的路径。需显式打包引用的图标图像文件。有关详细信息，请参阅打包图标图像文件和 `icon` 元数据。
`IconUrl`	`PackageIconUrl`	empty	弃用了 `PackageIconUrl` 以支持 `PackageIcon`。但为了获得最佳下层体验，除指定 `PackageIcon` 外，还应指定 `PackageIconUrl`。
`Readme`	`PackageReadmeFile`	empty	需显式打包引用的自述文件。
`Tags`	`PackageTags`	empty	标记的分号分隔列表，这些标记用于指定包。
`ReleaseNotes`	`PackageReleaseNotes`	empty	包的发行说明。
`Repository/Url`	`RepositoryUrl`	empty	用于克隆或检索源代码的存储库 URL。示例：https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git。
`Repository/Type`	`RepositoryType`	empty	存储库类型。示例：`git`（默认值）、`tfs`。
`Repository/Branch`	`RepositoryBranch`	empty	可选存储库分支信息。还必须指定 `RepositoryUrl` 才能包含此属性。示例：master（NuGet 4.7.0 及以上版本）。
`Repository/Commit`	`RepositoryCommit`	empty	可选的存储库提交或更改集，指示针对其生成包的源。还必须指定 `RepositoryUrl` 才能包含此属性。示例：0e4d1b598f350b3dc675018d539114d1328189ef（NuGet 4.7.0 及以上版本）。
`PackageType`	`<PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType>`		指示包的预期用途。包类型使用与包 ID 相同的格式，并用 `;` 进行分隔。可通过追加 `,` 和 `Version` 字符串对包类型进行版本控制。请参阅设置 NuGet 包类型（NuGet 3.5.0 及以上版本）。
`Summary`	不支持

包目标输入

properties	说明
`IsPackable`	一个指定能否打包项目的布尔值。默认值为 `true`。
`SuppressDependenciesWhenPacking`	设为 `true` 可不显示来自已生成 NuGet 包的包依赖项。
`PackageVersion`	指定生成的包所具有的版本。接受所有形式的 NuGet 版本字符串。默认为值 `$(Version)`，即项目中 `Version` 属性的值。
`PackageId`	指定生成的包的名称。如果未指定，`pack` 操作将默认使用 `AssemblyName` 或目录名称作为包的名称。
`PackageDescription`	用于 UI 显示的包的详细说明。
`Authors`	用分号分隔的包作者的列表，这些作者与 nuget.org 上的配置文件名称匹配。这些内容会显示在 nuget.org 的 NuGet 库中，且由同一作者用于交叉引用包。
`Description`	程序集的详细说明。如果未指定 `PackageDescription`，则此属性还可用作包的说明。
`Copyright`	包的版权详细信息。
`PackageRequireLicenseAcceptance`	一个布尔值，指定客户端是否必须提示使用者接受包许可证后才可安装包。默认为 `false`。
`DevelopmentDependency`	一个布尔值，用于指定包是否被标记为仅开发依赖项，从而防止包作为依赖项包含到其他包中。利用 `PackageReference`（NuGet 4.8 及以上版本），此标志还意味着将从编译中排除编译时资产。有关详细信息，请参阅 PackageReference 的 DevelopmentDependency 支持。
`PackageLicenseExpression`	SPDX 许可证标识符或表达式，例如 `Apache-2.0`。有关详细信息，请参阅打包许可证表达式或许可证文件。
`PackageLicenseFile`	如果使用的是自定义许可证或是没有分配 SPDX 标识符的许可证，则为包中许可证文件的路径。
`PackageLicenseUrl`	`PackageLicenseUrl` 已弃用。请改用 `PackageLicenseExpression` 或 `PackageLicenseFile`。
`PackageProjectUrl`
`PackageIcon`	指定相对于包的根目录的包图标路径。有关详细信息，请参阅打包图标图像文件。
`PackageReleaseNotes`	包的发行说明。
`PackageReadmeFile`	包的自述文件。
`PackageTags`	标记的分号分隔列表，这些标记用于指定包。
`PackageOutputPath`	确定用于已打包的包的输出路径。默认值为 `$(OutputPath)`。
`IncludeSymbols`	此布尔值指示在打包项目时，包是否应创建一个附加的符号包。符号包的格式由 `SymbolPackageFormat` 属性控制。有关详细信息，请参阅 IncludeSymbols。
`IncludeSource`	此布尔值指示包进程是否应创建源包。源包中包含库的源代码以及 PDB 文件。源文件置于生成的包文件中的 `src/ProjectName` 目录下。有关详细信息，请参阅IncludeSource。
`PackageType`
`IsTool`	指定是否将所有输出文件复制到 tools 文件夹，而不是 lib 文件夹。有关详细信息，请参阅IsTool。
`RepositoryUrl`	用于克隆或检索源代码的存储库 URL。示例：https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git。
`RepositoryType`	存储库类型。示例：`git`（默认值）、`tfs`。
`RepositoryBranch`	可选存储库分支信息。还必须指定 `RepositoryUrl` 才能包含此属性。示例：master（NuGet 4.7.0 及以上版本）。
`RepositoryCommit`	可选的存储库提交或更改集，指示针对其生成包的源。还必须指定 `RepositoryUrl` 才能包含此属性。示例：0e4d1b598f350b3dc675018d539114d1328189ef（NuGet 4.7.0 及以上版本）。
`SymbolPackageFormat`	指定符号包的格式。如果为“symbols.nupkg”，则会使用包含 PDB、DLL 和其他输出文件的 .symbols.nupkg 扩展来创建旧符号包。如果为“snupkg”，则会创建包含可移植 PDB 的 snupkg 符号包。默认值为“symbols.nupkg”。
`NoPackageAnalysis`	指定 `pack` 不应在生成包后运行包分析。
`MinClientVersion`	指定可安装此包的最低 NuGet 客户端版本，并由 nuget.exe 和 Visual Studio 包管理器强制实施。
`IncludeBuildOutput`	此布尔值指定是否应将生成输出程序集打包到 .nupkg 文件中。
`IncludeContentInPack`	此布尔值指定是否将含有 `Content` 类型的所有项目自动包含在生成的包中。默认为 `true`。
`BuildOutputTargetFolder`	指定放置输出程序集的文件夹。输出程序集（和其他输出文件）会复制到各自的框架文件夹中。有关详细信息，请参阅输出程序集。
`ContentTargetFolders`	指定放置所有内容文件的默认位置（如果未为其指定 `PackagePath`）。默认值为“content;contentFiles”。有关详细信息，请参阅在包中包含内容。
`NuspecFile`	当前用于打包的 .nuspec 文件的相对或绝对路径。如果已指定，则以独占方式将其用于打包信息，且不使用项目中的任何信息。有关更多信息，请参阅使用 .nuspec 进行打包。
`NuspecBasePath`	.nuspec 文件的基路径。有关更多信息，请参阅使用 .nuspec 进行打包。
`NuspecProperties`	键=值对的分号分隔列表。有关更多信息，请参阅使用 .nuspec 进行打包。

包方案

不显示依赖项

若要不显示来自已生成 NuGet 包的包依赖项，请将 SuppressDependenciesWhenPacking 设为 true 从而允许跳过已生成 nupkg 文件中的所有依赖项。

`PackageIconUrl`

现已弃用 PackageIconUrl 以便使用 PackageIcon 属性。从 NuGet 5.3 和 Visual Studio 2019 版本 16.3 开始，如果包元数据仅指定 PackageIconUrl，pack 则会引发 NU5048 警告。

`PackageIcon`

提示

若要保持与尚不支持 PackageIcon 的客户端和源的向后兼容性，则请同时指定 PackageIcon 和 PackageIconUrl。 Visual Studio 支持来自基于文件夹的源的包的对应 PackageIcon。

打包图标图像文件

打包图标图像文件时，使用 PackageIcon 属性指定相对于包根目录的图标文件路径。此外，请确保此文件包含在包中。图像文件大小被限制为 1 MB。支持的文件格式为 JPEG 和 PNG。建议使用分辨率为 128x128 的图像。

例如：

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

包图标示例。

为实现 nuspec 等效，请查看针对图标的 nuspec 参考。

PackageReadmeFile

通过 NuGet 5.10.0 预览版 2 / .NET SDK 5.0.300 以及以上版本提供支持

打包自述文件时，需使用 PackageReadmeFile 属性来指定相对于包的根目录的包路径。除此之外，还需确保此文件包含在包中。支持的文件格式仅为 Markdown (.md)。

例如：

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

为实现 nuspec 等效，请查看针对自述文件的 nuspec 参考。

输出程序集

nuget pack 会复制扩展名为 .exe、.dll、.xml、.winmd、.json 和 .pri 的输出文件。复制的输出文件取决于 MSBuild 从 BuiltOutputProjectGroup 目标提供的内容。

在项目文件或命令行中，有两个 MSBuild 属性可用于控制输出程序集的存储位置：

IncludeBuildOutput：确定包中是否应包括生成输出程序集的布尔值。
BuildOutputTargetFolder：指定应放置输出程序集的文件夹。输出程序集（和其他输出文件）会复制到各自的框架文件夹中。

包引用

请参阅项目文件中的包引用

项目到项目的引用

默认情况下，项目到项目的引用被视为 NuGet 包引用。例如：

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

也可将以下元数据添加到项目引用：

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

在包中添加内容

若要添加内容，请将额外的元数据添加到现有的 <Content> 项。默认情况下，类型“Content”的所有内容都包括在包中，除非使用以下条目替代：

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

默认情况下，所有内容都添加到包中 content 和 contentFiles\any\<target_framework> 文件夹根目录，并保留相对文件夹结构，除非指定包路径：

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

如果只想将所有内容都复制到特定根文件夹（而不是同时复制到 content 和 contentFiles），则可使用 MSBuild 属性 ContentTargetFolders（其默认值为“content;contentFiles”，但可设为任意其他文件夹名称。）请注意，基于 buildAction，仅在 ContentTargetFolders 中指定“contentFiles”会将文件置于 contentFiles\any\<target_framework> 或 contentFiles\<language>\<target_framework> 下。

PackagePath 可以是一组以分号分隔的目标路径。指定空的包路径会将文件添加到包的根目录。例如，以下操作会将 libuv.txt 添加到 content\myfiles、content\samples 和包的根目录：

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

另外还可使用 MSBuild 属性 $(IncludeContentInPack)（默认值为 true）。如果在任何项目中将此值设置为 false，则该项目的内容不会包括在 nuget 包中。

其他可在任意上述项目上设置的特定于包的元数据包括 <PackageCopyToOutput> 和 <PackageFlatten>，后者在输出 nuspec 中的 contentFiles 条目上会设置 CopyToOutput 和 Flatten 值。

注意

除了“Content”项，<Pack> 和 <PackagePath> 元数据还可以在具有 Compile、EmbeddedResource、ApplicationDefinition、Page、Resource、SplashScreen、DesignData、DesignDataWithDesignTimeCreateableTypes、CodeAnalysisDictionary、AndroidAsset、AndroidResource、BundleResource 或 None 生成操作的文件上进行设置。

使用通配模式时，对于将包的文件名追加到包路径，包路径必须以文件夹分隔符结尾，否则包路径将被视为包括文件名的完整路径。

IncludeSymbols

使用 MSBuild -t:pack -p:IncludeSymbols=true 时，相应的 .pdb 文件将随其他输出文件（.dll、.exe、.winmd、.xml、.json、.pri）一起复制。请注意，设置 IncludeSymbols=true 会创建常规包和符号包。

IncludeSource

这与 IncludeSymbols 相同，但它还会连同 .pdb 文件复制源文件。类型为 Compile 的所有文件都会复制到 src\<ProjectName>\，并保留生成包中的相对路径文件夹结构。对于将 TreatAsPackageReference 设为 false 的任意 ProjectReference 的源文件也是如此。

如果类型为 Compile 的文件位于项目文件夹外，则它只添加到了 src\<ProjectName>\。

打包许可证表达式或许可证文件

使用许可证表达式时，请使用 PackageLicenseExpression 属性。有关示例，请参阅许可证表达式示例。

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

若要详细了解 NuGet.org 接受的许可证表达式和许可证，请参阅许可证元数据。

打包许可证文件时，使用 PackageLicenseFile 属性指定相对于包的根目录的包路径。此外，请确保此文件包含在包中。例如：

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

有关示例，请参阅许可证文件示例。

注意

一次只能指定 PackageLicenseExpression、PackageLicenseFile 和 PackageLicenseUrl 中的一个。

打包没有扩展名的文件

某些情况下（例如打包许可证文件时），可能需包含没有扩展名的文件。出于历史原因，NuGet 和 MSBuild 会将没有扩展名的路径视为目录。

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>

没有扩展名的文件的示例。

IsTool

使用 MSBuild -t:pack -p:IsTool=true 时，所有输出文件（如输出程序集方案中所指定）都被复制到 tools 文件夹，而不是 lib 文件夹。请注意，这不同于 DotNetCliTool，后者通过在 .csproj 文件中设置 PackageType 进行指定。

使用 `.nuspec` 文件进行打包

尽管建议改为在项目文件中包括通常包含在 .nuspec 文件中的所有属性，但也可选择使用 .nuspec 文件来打包项目。对于使用 PackageReference 的非 SDK 式项目，必须导入 NuGet.Build.Tasks.Pack.targets 以便执行打包任务。仍需还原项目，才能打包 nuspec 文件。（默认情况下，SDK 式项目包括包目标。）

项目文件的目标框架无关紧要，且在打包 nuspec 时不会使用。以下三个 MSBuild 属性与使用 .nuspec 进行打包相关：

NuspecFile：用于打包的 .nuspec 文件的相对或绝对路径。
NuspecProperties：键=值对的分号分隔列表。由于 MSBuild 命令行分析的工作方式，必须指定多个属性，如下所示：-p:NuspecProperties="key1=value1;key2=value2"。
NuspecBasePath：.nuspec 文件的基路径。

如果使用 dotnet.exe 打包项目，请使用类似于下面的命令：

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

如果使用 MSBuild 打包项目，请使用类似于下面的命令：

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path>

请注意，使用 dotnet.exe 或 msbuild 打包 nuspec 也会导致默认生成项目。可通过将 --no-build 属性传递给 dotnet.exe 来避免此情况，而这与在项目文件中设置 <NoBuild>true</NoBuild> 以及在项目文件中设置 <IncludeBuildOutput>false</IncludeBuildOutput> 等效。

用于打包 nuspec 文件的 .csproj 文件的示例如下：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

用于创建自定义包的高级扩展点

pack 目标提供两个扩展点，而这些扩展点会在内部特定于目标框架的生成中运行。这些扩展点支持将特定于目标框架的内容和程序集包括到包中：

TargetsForTfmSpecificBuildOutput 目标：用于 lib 文件夹中的文件，或是使用 BuildOutputTargetFolder 指定的文件夹中的文件。
TargetsForTfmSpecificContentInPackage 目标：用于 BuildOutputTargetFolder 外部的文件。

`TargetsForTfmSpecificBuildOutput`

编写自定义目标并将其指定为 $(TargetsForTfmSpecificBuildOutput) 属性的值。对于需进入 BuildOutputTargetFolder（默认为 lib）的所有文件，此目标均应将这些文件写入 ItemGroup BuildOutputInPackage 并设置以下两个元数据值：

FinalOutputPath：此文件的绝对路径；如果未提供，则使用“标识”来评估源路径。
TargetPath：（可选）设置此文件何时需进入 lib\<TargetFramework> 中的子文件夹，例如进入其各自区域性文件夹的附属程序集。默认为此文件的名称。

示例：

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

`TargetsForTfmSpecificContentInPackage`

编写自定义目标并将其指定为 $(TargetsForTfmSpecificContentInPackage) 属性的值。对于要纳入包中的所有文件，此目标均应将这些文件写入 ItemGroup TfmSpecificPackageFile 并设置以下可选元数据：

PackagePath：此文件应在包中输出的路径。如果将多个文件添加到同一包路径，NuGet 则会发出警告。
BuildAction：要分配给此文件的生成操作，它仅在包路径位于 contentFiles 文件夹中时才需使用。默认为“None”。

示例：

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>

还原目标

MSBuild -t:restore（nuget restore 和 dotnet restore 与 .NET Core 项目一起使用）会还原项目文件中引用的包，如下所示：

读取所有项目到项目的引用
读取项目属性以查找中间文件夹和目标框架
将 MSBuild 数据传递给 NuGet.Build.Tasks.dll
运行还原
下载包
编写资产文件、目标和属性

restore 目标适用于采用 PackageReference 格式的项目。 MSBuild 16.5+ 还为 packages.config 格式提供选择加入支持。

注意

restore 目标不应与 build 目标组合运行。

还原属性

其他还原设置可能来自项目文件中的 MSBuild 属性。还可以从命令行使用 -p: 开关设置值（请参阅以下示例）。

properties	说明
`RestoreSources`	以分号分隔的包源列表。
`RestorePackagesPath`	用户包文件夹路径。
`RestoreDisableParallel`	将下载限制为一次一个。
`RestoreConfigFile`	要应用的 `Nuget.Config` 文件的路径。
`RestoreNoHttpCache`	如果为 true，则避免使用 http 缓存包。请参阅管理全局包和缓存文件夹。
`RestoreIgnoreFailedSources`	如果为“true”，则忽略失败或丢失的包源。
`RestoreFallbackFolders`	回退文件夹，其使用方式与用户包文件夹的使用相同。
`RestoreAdditionalProjectSources`	还原期间要使用的其他源。
`RestoreAdditionalProjectFallbackFolders`	还原期间要使用的其他回退文件夹。
`RestoreAdditionalProjectFallbackFoldersExcludes`	排除在 `RestoreAdditionalProjectFallbackFolders` 中指定的回退文件夹
`RestoreTaskAssemblyFile`	`NuGet.Build.Tasks.dll` 的路径。
`RestoreGraphProjectInput`	要还原的以分号分隔的项目列表，其中应包含绝对路径。
`RestoreUseSkipNonexistentTargets`	通过 MSBuild 收集项目时，它会确定是否使用 `SkipNonexistentTargets` 优化来收集它们。如果未设置，则默认为 `true`。无法导入项目的目标时，后果为一种快速失败行为。
`MSBuildProjectExtensionsPath`	输出文件夹，默认为 `BaseIntermediateOutputPath` 和 `obj` 文件夹。
`RestoreForce`	在基于 PackageReference 的项目中，强制解析所有依赖项，即使上次还原已成功。指定此标志类似于删除 `project.assets.json` 文件。这不会绕过 http-cache。
`RestorePackagesWithLockFile`	选择使用锁定文件。
`RestoreLockedMode`	以锁定模式运行还原。这意味着还原不会重新评估依赖项。
`NuGetLockFilePath`	锁定文件的自定义位置。默认位置位于项目旁边，并被命名为 `packages.lock.json`。
`RestoreForceEvaluate`	强制还原重新计算依赖项并更新锁定文件，而不发出任何警告。
`RestorePackagesConfig`	选择加入开关，它可还原带 packages.config 的项目。仅支持 `MSBuild -t:restore`。
`RestoreRepositoryPath`	仅 packages.config。指定要将包还原到的包目录。如果未指定，则使用 `SolutionDirectory`。
`RestoreUseStaticGraphEvaluation`	选择加入开关，它允许使用静态图 MSBuild 评估，而不是标准评估。静态图评估是一项实验性功能，它对于大型存储库和解决方案要快得多。
`RestoreUseLegacyDependencyResolver`	选择不使用旧依赖项解析程序。在 6.12 版本中重写了 NuGet 的依赖项解析程序实现。此开关强制使用以前的算法。

ExcludeRestorePackageImports 属性是 NuGet 使用的一个内部属性。它不应进行修改，也不应在任意 MSBuild 文件中进行设置。

示例

命令行：

msbuild -t:restore -p:RestoreConfigFile=<path>

项目文件：

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

还原输出

还原会在生成 obj 文件夹中创建以下文件：

文件	说明
`project.assets.json`	包含所有包引用的依赖项关系图。
`{projectName}.projectFileExtension.nuget.g.props`	对包中所含 MSBuild 属性的引用
`{projectName}.projectFileExtension.nuget.g.targets`	对包中所含 MSBuild 目标的引用

使用一个 MSBuild 命令来还原和生成

由于 NuGet 可还原导致 MSBuild 目标和属性失效的包，还原和生成评估会使用不同的全局属性来运行。这意味着以下内容将出现不可预知且经常不正确的行为。

msbuild -t:restore,build

推荐的方法为：

msbuild -t:build -restore

同一逻辑也适用于类似 build 的其他目标。

还原具有 MSBuild 的 PackageReference 和 packages.config 项目

对于 MSBuild 16.5 及以上版本，还为 msbuild -t:restore 支持使用 packages.config。

msbuild -t:restore -p:RestorePackagesConfig=true

注意

packages.config 还原仅适用于 MSBuild 16.5+，而不适用于 dotnet.exe

使用 MSBuild 静态图评估来还原

注意

对于 MSBuild 16.6 及以上版本，NuGet 添加了一项实验性功能，它可从命令行使用静态图评估，从而大幅缩短针对大型存储库的还原时间。

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

或者，也可通过在 Directory.Build.Props 中设置该属性来启用此功能。

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

注意

从 Visual Studio 2019.x 和 NuGet 5.x 开始，此功能被视为实验性功能和选择加入功能。有关默认情况下何时会启用此功能的详细信息，请按 NuGet/Home#9803 进行操作。

静态图还原会更改还原的 msbuild 部分、项目读取和评估，但不更改还原算法！还原算法在所有 NuGet 工具（NuGet.exe、MSBuild.exe、dotnet.exe 和 Visual Studio）中均相同。

极少数情况下，静态图还原的行为可能与当前还原有所不同，且可能会缺少某些已声明的 PackageReferences 或 ProjectReferences。

若要缓解此问题，作为一次性检查，请在迁移到静态图还原时考虑运行：

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGet 不应报告任何更改。如果发现差异，请在 NuGet/Home 中提交问题。

从还原图中替换一个库

如果还原引入了错误的程序集，可以排除包默认选项，并将其替换为自己的选项。首先使用顶级 PackageReference，排除所有资产：

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

接下来，将自己的引用添加到适当的 DLL 本地副本：

<Reference Include="Newtonsoft.Json.dll" />

通过

将 NuGet pack 和 restore 用作 MSBuild 目标

目标生成顺序

包目标

包目标输入

包方案

不显示依赖项

`PackageIconUrl`

`PackageIcon`

打包图标图像文件

PackageReadmeFile

输出程序集

包引用

项目到项目的引用

在包中添加内容

IncludeSymbols

IncludeSource

打包许可证表达式或许可证文件

打包没有扩展名的文件

IsTool

使用 `.nuspec` 文件进行打包

用于创建自定义包的高级扩展点

`TargetsForTfmSpecificBuildOutput`

`TargetsForTfmSpecificContentInPackage`

还原目标

还原属性

示例

还原输出

使用一个 MSBuild 命令来还原和生成

还原具有 MSBuild 的 PackageReference 和 packages.config 项目

使用 MSBuild 静态图评估来还原

从还原图中替换一个库

反馈

其他资源

通过

将 NuGet pack 和 restore 用作 MSBuild 目标

目标生成顺序

包目标

包目标输入

包方案

不显示依赖项

PackageIconUrl

PackageIcon

打包图标图像文件

PackageReadmeFile

输出程序集

包引用

项目到项目的引用

在包中添加内容

IncludeSymbols

IncludeSource

打包许可证表达式或许可证文件

打包没有扩展名的文件

IsTool

使用 .nuspec 文件进行打包

用于创建自定义包的高级扩展点

TargetsForTfmSpecificBuildOutput

TargetsForTfmSpecificContentInPackage

还原目标

还原属性

示例

还原输出

使用一个 MSBuild 命令来还原和生成

还原具有 MSBuild 的 PackageReference 和 packages.config 项目

使用 MSBuild 静态图评估来还原

从还原图中替换一个库

反馈

其他资源

`PackageIconUrl`

`PackageIcon`

使用 `.nuspec` 文件进行打包

`TargetsForTfmSpecificBuildOutput`

`TargetsForTfmSpecificContentInPackage`