dotnet restore

本文适用于： ✔️ .NET Core 3.1 SDK 及更高版本

“属性”

dotnet restore - 恢复项目的依赖项和工具。

摘要

dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-build-servers]
    [--disable-parallel]
    [-f|--force] [--force-evaluate] [--ignore-failed-sources]
    [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
    [--no-cache] [--no-dependencies] [--packages <PACKAGES_DIRECTORY>]
    [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
    [--tl:[auto|on|off]] [--use-current-runtime, --ucr [true|false]]
    [--use-lock-file] [-v|--verbosity <LEVEL>]

dotnet restore -h|--help

说明

.NET 项目通常引用 NuGet 包中提供附加功能的外部库。 在项目文件（.csproj 或 .vbproj）中引用这些外部依赖项。 运行 dotnet restore 命令时，.NET CLI 使用 NuGet 查找这些依赖项，并在必要时下载它们。 它还可确保项目所需的所有依赖项彼此兼容，并且它们之间没有冲突。 命令完成后，项目所需的所有依赖项都将在本地缓存中提供，.NET CLI 可以使用这些依赖项生成和运行应用程序。

在大多数情况下，不需要显式使用 dotnet restore 命令，因为如果需要进行 NuGet 还原，则以下命令会隐式运行它：

• dotnet new
• dotnet build
• dotnet build-server
• dotnet run
• dotnet test
• dotnet publish
• dotnet pack

有时，通过这些命令运行隐式 NuGet 还原可能不方便。 例如，某些自动化系统（如生成系统）需要显式调用 dotnet restore，以控制还原发生的时间，以便可以控制网络使用量。 为了防止运行隐式 NuGet 还原，可以通过上述任意命令使用 --no-restore 标记。

注意

还原操作期间的签名包验证需要对代码签名和时间戳都有效的证书根存储。 有关详细信息，请参阅 NuGet 签名的包验证。

指定源

为了还原依赖项，NuGet 需要包所在的源。 通常通过“nuGet.config”配置文件提供源。 安装 .NET SDK 时提供一个默认的配置文件。 若要指定其他源，请执行以下任一项操作：

• 在项目目录中创建自己的 nuget.config 文件。 有关详细信息，请参阅本文后面介绍的常见 NuGet 配置和 nuget.config 差异。
• 使用诸如 dotnet nuget add source 等 dotnet nuget 命令。

可以使用 -s 选项替代 nuget.config 源。

有关如何使用经过身份验证的源的信息，请参阅使用经过身份验证的源中的包。

全局包文件夹

对于依赖项，可以使用 --packages 参数指定还原操作期间放置还原包的位置。 如未指定，将使用默认的 NuGet 包缓存，可在所有操作系统上的用户主目录中的 .nuget/packages 目录找到它。 例如 Linux 上的 /home/user1 或 Windows 上的 C:\Users\user1 。

特定于项目的工具

对于特定于项目的工具，dotnet restore 首先还原打包工具所在的包，然后继续还原 project 文件中指定的工具依赖项。

nuget.config 差异

dotnet restore 命令的行为会受 Nuget.Config 文件（如果有）中某些设置的影响。 例如，在 NuGet.Config 中设置 globalPackagesFolder 会将还原的 NuGet 包置于指定的文件夹中。 这是在 dotnet restore 命令中指定 --packages 选项的替代方法。 有关详细信息，请参阅 nuget.config 参考。

有三个 dotnet restore 可忽略的特定设置：

• bindingRedirects

  绑定重定向不适用于 <PackageReference> 元素，并且 .NET 仅支持 NuGet 包的 <PackageReference> 元素。

• 解决方案

  此设置特定于 Visual Studio，不适用于 .NET。 .NET 不使用 packages.config 文件，而是使用 NuGet 包的 <PackageReference> 元素。

• trustedSigners

  .NET 5.0.100 SDK 中添加了对跨平台包签名验证的支持。

工作负载清单下载

运行此命令时，它将为工作负载启动播发清单的异步后台下载。 如果此命令完成后，下载仍在运行，则将停止下载。 有关详细信息，请参阅播发清单。

自变量

• ROOT

  要还原的项目文件的可选路径。

选项

• -a|--arch <ARCHITECTURE>

  指定目标体系结构。 这是用于设置运行时标识符 (RID) 的简写语法，其中提供的值与默认 RID 相结合。 例如，在 win-x64 计算机上，指定 --arch x86 会将 RID 设置为 win-x86。 如果使用此选项，请不要使用 -r|--runtime 选项。 从 .NET 6 Preview 7 开始提供。

• --configfile <FILE>

  要使用的 NuGet 配置文件 (nuget.config)。 如果指定，则只使用此文件中的设置。 如果不指定，将使用当前目录中的配置文件的层次结构。 有关详细信息，请参阅常见的 NuGet 配置。

• --disable-build-servers

  强制运行命令以忽略任何永久性生成服务器。 此选项提供一种一致的方法来禁止对生成缓存的所有使用，这会强制从头开始生成。 当缓存可能由于某种原因而损坏或不正确时，不依赖缓存的生成非常有用。 自 .NET 7 SDK 起可用。

• --disable-parallel

  禁用并行还原多个项目。

• --force

  强制解析所有依赖项，即使上次还原已成功，也不例外。 指定此标记等同于删除 project.assets.json 文件。

• --force-evaluate

  即使锁定文件已存在，也会强制还原以重新评估所有依赖项。

• -?|-h|--help

  打印出有关如何使用命令的说明。

• --ignore-failed-sources

  如果存在符合版本要求的包，则源失败时警告。

• --interactive

  允许命令停止并等待用户输入或操作。 例如，完成身份验证。

• --lock-file-path <LOCK_FILE_PATH>

  写入项目锁定文件的输出位置。 默认情况下，此位置为 PROJECT_ROOT \packages.lock.json。

• --locked-mode

  不允许更新项目锁定文件。

• --no-cache

  指定不缓存 HTTP 请求。

• --no-dependencies

  当使用项目到项目 (P2P) 引用还原项目时，还原根项目，不还原引用。

• --packages <PACKAGES_DIRECTORY>

  指定还原包的目录。

• -r|--runtime <RUNTIME_IDENTIFIER>

  指定程序包还原的运行时。 这用于还原 .csproj 文件中的 <RuntimeIdentifiers> 标记中未显式列出的运行时的程序包。 有关运行时标识符 (RID) 的列表，请参阅 RID 目录。

• -s|--source <SOURCE>

  指定要在还原操作期间使用的 NuGet 包源的 URI。 此设置会替代 nuget.config 文件中指定的所有源。 多次指定此选项可以提供多个源。

• --tl:[auto|on|off]

  指定是否应将终端记录器用于生成输出。 默认值为 auto，它首先验证环境，然后再启用终端日志记录。 在启用新的记录器之前，环境检查会验证终端能否使用新式输出功能，并且不使用重定向的标准输出。 on 跳过环境检查并启用终端日志记录。 off 跳过环境检查并使用默认控制台记录器。

  终端记录器显示还原阶段，然后显示生成阶段。 在每个阶段，当前生成项目显示在终端的底部。 每个正在生成的项目都会输出当前正在生成的 MSBuild 目标，以及在该目标上花费的时间。 可以搜索此信息以了解有关生成的详细信息。 项目生成完成后，将会编写一个“已完成生成”部分以捕获以下内容：

  • 生成项目的名称。
  • 目标框架（如果是多目标）。
  • 该生成的状态。
  • 该生成的主要输出（它设置了超链接）。
  • 为该项目生成的任何诊断。

  此选项从 .NET 8 开始可用。

• --use-current-runtime, --ucr [true|false]

  根据计算机之一将 RuntimeIdentifier 设置为平台可移植的 RuntimeIdentifier。 需要 RuntimeIdentifier（例如 SelfContained、PublishAot、PublishSelfContained、PublishSingleFile 和 PublishReadyToRun）的属性会隐式发生这种情况。 如果该属性设置为 false，则不再发生隐式解析。

• --use-lock-file

  允许生成项目锁定文件并与还原一起使用。

• -v|--verbosity <LEVEL>

  设置命令的详细级别。 允许使用的值为 q[uiet]、m[inimal]、n[ormal]、d[etailed] 和 diag[nostic]。 默认值为 minimal。 有关详细信息，请参阅 LoggerVerbosity。

示例

• 还原当前目录中项目的依赖项和工具：

  dotnet restore
  

• 还原在给定路径中找到的 app1 项目的依赖项和工具：

  dotnet restore ./projects/app1/app1.csproj
  

• 通过将提供的文件路径用作源，在当前目录中还原项目的依赖项和工具：

  dotnet restore -s c:\packages\mypackages
  

• 通过将提供的两个文件路径用作源，在当前目录中还原项目的依赖项和工具：

  dotnet restore -s c:\packages\mypackages -s c:\packages\myotherpackages
  

• 还原当前目录中项目的依赖项和工具，并显示详细的输出：

  dotnet restore --verbosity detailed
  

对安全漏洞进行审核

从 .NET 8 开始，可以选择进行 NuGet 安全审核，以便使用 dotnet restore。 此审核会生成一份安全漏洞报告，其中包含受影响的包名称、漏洞的严重性，以及有关更多详细信息的公告链接。

若要选择进行安全审核，请在项目文件中将 <NuGetAudit> MSBuild 属性设置为 true。 此外，若要检索已知的漏洞数据集，请确保已将 NuGet.org 中央注册表定义为包源之一：

<packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
</packageSources>

可以通过设置 <NuGetAuditLevel> MSBuild 属性来配置审核失败的级别。 可能值为 low、moderate、high 和 critical。 例如，如果只想查看中等、高等和关键公告，可以将属性设置为 moderate。