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 還原時,下列命令會隱含地執行它:
有時候,使用這些命令執行隱含 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
會先還原在其中封裝工具的套件,然後繼續還原其專案檔中所指定的工具相依性。
nuget.config 檔案中設定 (如果有的話) 會影響 dotnet restore
命令的行為。 例如,在 nuget.config 中設定 globalPackagesFolder
會將還原的 NuGet 套件置於所指定資料夾。 這是在 dotnet restore
命令上指定 --packages
選項的替代方式。 如需詳細資訊,請參閱 nuget.config 參考。
dotnet restore
會忽略三個特定設定:
-
繫結重新導向不適用於
<PackageReference>
元素,且 .NET 僅支援 NuGet 套件的<PackageReference>
元素。 -
這是 Visual Studio 的特定設定,不適用於 .NET。 .NET 不是使用
packages.config
檔案,而是使用 NuGet 套件的<PackageReference>
元素。 -
.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 開始, dotnet restore
包含 NuGet 安全性稽核。 此稽核會產生安全性弱點的報告,其中包含受影響的套件名稱、弱點的嚴重性,以及用來取得詳細資料的諮詢連結。
若要選擇宣告安全性稽核,請將 <NuGetAudit>
項目檔中的 MSBuild 屬性設定為 false
。
若要擷取已知的弱點數據集,請確定您已將 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
。
從 .NET 9 開始,NuGet 預設會 稽核直接 和 可轉移的 套件參考。 在 .NET 8 中,只會 稽核直接 套件參考。 您可以將 MSBuild 屬性設定為 direct
或 all
來<NuGetAuditMode>
變更模式。
如需詳細資訊,請參閱 稽核安全性弱點的套件相依性。