共用方式為

dotnet package add

本文適用於： ✔️ .NET Core 3.1 SDK 與更新版本

名稱

dotnet package add - 在項目檔中新增或更新套件參考。

備註

如果您使用 .NET 9 SDK 或更早版本，請改用 “verb first” 窗體 （dotnet add package） 。 「名詞優先」表單是在 .NET 10 中引進的。 如需詳細資訊，請參閱 更一致的命令順序。

概要

dotnet package add <PACKAGE_NAME>
    [-f|--framework <FRAMEWORK>] [--interactive] [--project <PROJECT>]
    [-n|--no-restore] [--package-directory <PACKAGE_DIRECTORY>]
    [--prerelease] [-s|--source <SOURCE>] [-v|--version <VERSION>]

dotnet package add -h|--help

說明

dotnet package add命令提供方便的選項，可在項目檔中新增或更新套件參考。 當您執行 命令時，會有相容性檢查，以確保套件與專案中的架構相容。 如果檢查通過，而且項目檔中未參考封裝， <PackageReference> 則會將專案新增至項目檔。 如果檢查通過，且項目檔中已參考封裝，元素 <PackageReference> 就會更新為最新的相容版本。 更新項目檔之後，即會執行 dotnet restore 。

例如，新增 Microsoft.EntityFrameworkCore 至 ToDo.csproj 會產生類似下列範例的輸出：

  Determining projects to restore...
  Writing C:\Users\username\AppData\Local\Temp\tmp24A8.tmp
info : Adding PackageReference for package 'Microsoft.EntityFrameworkCore' into project 'C:\ToDo\ToDo.csproj'.
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/index.json
info :   GET https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/0.0.1-alpha/3.1.3.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/3.1.4/7.0.0-preview.2.22153.1.json
info :   CACHE https://api.nuget.org/v3/registration5-gz-semver2/microsoft.entityframeworkcore/page/7.0.0-preview.3.22175.1/7.0.0-preview.3.22175.1.json
info :   NotFound https://pkgs.dev.azure.com/dnceng/9ee6d478-d288-47f7-aacc-f6e6d082ae6d/_packaging/516521bf-6417-457e-9a9c-0a4bdfde03e7/nuget/v3/registrations2-semver2/microsoft.entityframeworkcore/index.json 257ms
info : Restoring packages for C:\ToDo\ToDo.csproj...
info : Package 'Microsoft.EntityFrameworkCore' is compatible with all the specified frameworks in project 'C:\ToDo\ToDo.csproj'.
info : PackageReference for package 'Microsoft.EntityFrameworkCore' version '6.0.4' added to file 'C:\ToDo\ToDo.csproj'.
info : Writing assets file to disk. Path: C:\ToDo\obj\project.assets.json
log  : Restored C:\ToDo\ToDo.csproj (in 171 ms).

ToDo.csproj 檔案現在包含<PackageReference>參考套件的 元素。

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

如果專案已上線至 中央套件管理 （CPM）， 則 <PackageVersion> 中的 Directory.Packages.props file 元素會新增/更新，並將 <PackageReference> 專案新增至項目檔。

目前支援下列案例。 這些範例假設 的最新版本 Microsoft.EntityFrameworkCore 是 6.0.4。 此設計規格記載了與 CPM 相關的其他案例。

案例 1： <PackageReference> 不存在於項目檔中， <PackageVersion> 元素不存在於 中 Directory.Packages.props file，而且版本自變數不會從命令行傳遞。

執行的 CLI 命令： dotnet package add Microsoft.EntityFrameworkCore --project ToDo.csproj

專案 <PackageVersion> 會加入至 Directory.Packages.props file。

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

專案 <PackageReference> 會新增至項目檔。

<PackageReference Include="Microsoft.EntityFrameworkCore" />

案例 2： <PackageReference> 不存在於項目檔中， <PackageVersion> 專案不存在於 中 Directory.Packages.props file，而且版本自變數會從命令行傳遞。

執行的 CLI 命令： dotnet package add Microsoft.EntityFrameworkCore --version 5.0.4 --project ToDo.csproj

專案 <PackageVersion> 會加入至 Directory.Packages.props file。

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

專案 <PackageReference> 會新增至項目檔。

<PackageReference Include="Microsoft.EntityFrameworkCore" />

案例 3：<PackageReference>不存在於項目檔中，項目確實存在於 中Directory.Packages.props file，<PackageVersion>而且版本自變數不會從命令行傳遞。

執行的 CLI 命令： dotnet package add Microsoft.EntityFrameworkCore --project ToDo.csproj

專案 <PackageVersion> 會加入至 Directory.Packages.props file。

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="6.0.4" />

專案 <PackageReference> 會新增至項目檔。

<PackageReference Include="Microsoft.EntityFrameworkCore" />

案例 4： <PackageReference> 不存在於項目檔中， <PackageVersion> 項目確實存在於 中 Directory.Packages.props file，而且版本自變數會從命令行傳遞。

執行的 CLI 命令： dotnet package add Microsoft.EntityFrameworkCore --version 5.0.4 --project ToDo.csproj

專案 <PackageVersion> 會加入至 Directory.Packages.props file。

<PackageVersion Include="Microsoft.EntityFrameworkCore" Version="5.0.4" />

專案 <PackageReference> 會新增至項目檔。

<PackageReference Include="Microsoft.EntityFrameworkCore" />

隱含還原

您不必執行 dotnet restore，因為其會由需要進行還原的所有命令隱含執行，例如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要停用隱含還原，請使用 --no-restore 選項。

dotnet restore 命令在適合進行明確還原的特定案例中仍可派上用場，例如 Azure DevOps Services 中的持續整合組建，或在需要明確控制何時進行還原的組建系統中。

若要了解如何管理 NuGet 套件源，請參閱 dotnet restore 文件。

論點

  • PROJECT

    指定項目檔。 如果未指定，命令會搜尋目前目錄的其中一個目錄。

  • PACKAGE_NAME

    要加入的套件參考。

選項

  • -f|--framework <FRAMEWORK>

    只有在以特定 架構為目標時，才新增套件參考。

  • -?|-h|--help

    輸出有關如何使用命令的說明。

  • --interactive

    可讓命令停止，並等候使用者輸入或進行動作。 例如完成驗證。

  • -n|--no-restore

    新增套件參考，而不執行還原預覽和相容性檢查。

  • --package-directory <PACKAGE_DIRECTORY>

    要還原封裝的目錄。 默認套件還原位置位於 %userprofile%\.nuget\packages Windows 和 ~/.nuget/packages macOS 和 Linux 上。 如需詳細資訊，請參閱 管理 NuGet 中的全域套件、快取和暫存資料夾。

  • --prerelease

    允許安裝發行前版本套件。 自 .NET Core 5 SDK 起提供

  • -s|--source <SOURCE>

    還原作業期間要使用的 NuGet 套件來源 URI。

  • -v|--version <VERSION>

    套件的版本。 請參閱 NuGet 套件版本控制。

範例

  • 將 NuGet 套件新增 Microsoft.EntityFrameworkCore 至專案：

    dotnet package add Microsoft.EntityFrameworkCore

  • 將套件的特定版本新增至專案：

    dotnet package add Microsoft.Azure.DocumentDB.Core -v 1.0.0 --project ToDo.csproj

  • 使用特定的 NuGet 來源新增套件：

    dotnet package add Microsoft.AspNetCore.StaticFiles -s https://dotnet.myget.org/F/dotnet-core/api/v3/index.json

另請參閱