NuGet

發行項
01/29/2025

NuGet 是 .NET 生態系統的套件管理員，也是開發人員探索及取得 .NET 開放原始碼連結庫的主要方式。 NuGet.org，Microsoft為裝載 NuGet 套件提供的免費服務，是公用 NuGet 套件的主要主機，但您可以發佈至自定義 NuGet 服務，例如 MyGet 和 Azure Artifacts。

建立 NuGet 套件

NuGet 套件（*.nupkg）是包含 .NET 元件和相關聯元數據的 zip 檔案。

有兩個主要方式可以建立 NuGet 套件。較新的和建議方式是從 SDK 樣式專案建立套件（其內容開頭為 <Project Sdk="Microsoft.NET.Sdk">的項目檔）。元件和目標會自動新增至套件，其餘元數據會新增至 MSBuild 檔案，例如套件名稱和版本號碼。使用 dotnet pack 命令編譯會輸出 *.nupkg 檔案，而不是元件。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

建立 NuGet 套件的較舊方式是使用 *.nuspec 檔案和 nuget.exe 命令行工具。 nuspec 檔案提供您絕佳的控制權，但您必須仔細指定要包含在最終 NuGet 套件中的元件和目標。很容易犯錯，或有人在進行變更時遺忘了更新nuspec。 nuspec 的優點是，您可以使用它來建立尚未支援 SDK 樣式專案檔之架構的 NuGet 套件。

✔️ 請考慮使用 SDK 樣式的項目檔來建立 NuGet 套件。

套件相依性

相依性一文中會詳細說明 NuGet 套件相依性。

重要 NuGet 套件元數據

NuGet 套件支援許多元資料屬性。下表包含 NuGet.org 上每個套件都應該提供的核心元數據：

MSBuild 屬性名稱	Nuspec 名稱	描述
`PackageId`	`id`	封裝標識碼。如果識別元符合準則，則可以保留識別碼的前置詞。
`PackageVersion`	`version`	NuGet 套件版本。如需詳細資訊，請參閱 NuGet 套件版本。
`Title`	`title`	套件的使用者友善標題。預設為 `PackageId`。
`Description`	`description`	UI 中顯示的封包詳細描述。
`Authors`	`authors`	將套件作者的名稱以逗號分隔，這些名稱應對應到 nuget.org 上的個人檔案名稱。
`PackageTags`	`tags`	描述套件的標籤和關鍵詞的空格或分號分隔清單。搜尋套件時會使用標記。
`PackageIcon`	`icon`	封裝中要做為封裝圖示之映像的路徑。深入瞭解 `icon` 元數據。
`PackageProjectUrl`	`projectUrl`	專案首頁或來源存放庫的 URL。
`PackageLicenseExpression`	`license`	項目授權的 SPDX 識別碼。只有 OSI 和 FSF 核准的授權可以使用識別碼。其他授權應該使用 `PackageLicenseFile`。深入瞭解 `license` 元數據。

重要

未持有許可證的項目默認為獨占版權，這使其他人無法合法使用。

✔️ 請考慮選擇一個 NuGet 套件名稱，其前綴詞符合 NuGet 前綴詞保留準則。

✔️ 請對套件圖示使用 HTTPS href。

像 NuGet.org 這類啟用了 HTTPS 的網站，顯示非 HTTPS 影像將會導致混合內容警告。

✔️ 請使用 64x64 且具有透明背景的套件圖示影像，以獲得最佳檢視結果。

✔️ 請考慮設定 Source Link，將原始檔控制元數據新增至您的元件和 NuGet 套件。

來源鏈接會自動將 RepositoryUrl 和 RepositoryType 元數據新增至 NuGet 套件。 Source Link 也會新增套件所建置之確切原始程式碼的相關信息。例如，從 Git 存放庫建立的套件將把提交哈希新增為中繼資料。

發行前版本套件

具有版本後綴的 NuGet 套件會被視為發行前版本。根據預設，NuGet 套件管理員 UI 會顯示穩定版本，除非使用者選擇加入發行前版本套件，讓發行前版本套件很適合用於有限的用戶測試。

<PackageVersion>1.0.1-beta1</PackageVersion>

注意

穩定套件不能相依於發行前版本套件。您必須建立自己的套件發行前版本，或相依於較舊的穩定版本。

NuGet 發行前版本套件相依性

✔️ 在測試、預覽或實驗時，請發佈預覽版套件。

✔️ 當您準備好穩定套件時，請發佈穩定套件，讓其他穩定套件可以參考它。

符號套件

符號檔（*.pdb）是由 .NET 編譯程式與元件一起產生。符號檔會將執行位置對應至原始程式碼，讓您可以在使用調試程式時逐步執行原始程式碼。 NuGet 支援產生一個包含符號檔案的獨立符號套件（*.snupkg），與包含 .NET 程式集的主要套件一起提供。符號套件的概念是它們裝載在符號伺服器上，而且只會由 Visual Studio 等工具視需要下載。

NuGet.org 託管自己的符號伺服器存放庫，。開發人員可以使用發佈至 NuGet.org 符號伺服器的符號，方法是將 https://symbols.nuget.org/download/symbols 新增至 Visual Studio 中的符號來源。

重要

NuGet.org 符號伺服器僅支援 SDK 樣式專案所建立的新可攜式符號檔（*.pdb）。

若要在偵錯 .NET 連結庫時使用 NuGet.org 符號伺服器，開發人員必須具有Visual Studio 2017 15.9版或更新版本。

建立符號套件的替代方案是將符號檔內嵌在主要 NuGet 套件中。主要 NuGet 套件將會較大，但內嵌的符號檔表示開發人員不需要設定 NuGet.org 符號伺服器。如果您要使用 SDK 樣式專案建置 NuGet 套件，則可以藉由設定 AllowedOutputExtensionsInPackageBuildOutputFolder 屬性來內嵌符號檔：

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

內嵌符號檔的缺點是，它們會使使用 SDK 樣式專案編譯的 .NET 程式庫的套件大小增加約 30%。如果套件大小是問題，您應該改為在符號套件中發佈符號。

✔️ 請考慮將符號發佈為符號套件（*.snupkg），以 NuGet.org

符號套件（*.snupkg）為開發人員提供良好的隨選偵錯體驗，而不會讓主要套件大小膨脹，並影響不想要偵錯 NuGet 套件的使用者的還原效能。

請注意，使用者可能需要在其 IDE 中尋找並設定 NuGet 符號伺服器（做為一次性設定），才能取得符號檔。 Visual Studio 2019 16.1 版已將 NuGet.org 的符號伺服器新增至預設符號伺服器清單。

上一個下一個

共用方式為