使用 dotnet CLI 建立 NuGet 套件

發行項
12/14/2023

NuGet 套件包含程式代碼，開發人員可以在其專案中重複使用。無論您的程式代碼包含什麼，您都使用或命令行工具nuget.exedotnet.exe來建立 NuGet 套件。

本文說明如何使用 dotnet CLI 建立套件。從 Visual Studio 2017 開始，dotnet CLI 隨附於所有 .NET 和 .NET Core 工作負載。如果您需要安裝 dotnet CLI 或其他 NuGet 用戶端工具，請參閱安裝 NuGet 用戶端工具。

本主題僅適用於使用SDK樣式格式的 .NET 和其他專案。針對這些專案，NuGet 會使用專案檔中的資訊來建立套件。如需快速入門教學課程，請參閱使用 dotnet CLI 建立套件或使用 Visual Studio 建立套件。

MSBuild msbuild -t：pack 命令的功能相當於 dotnet pack。如需使用 MSBuild 建立套件的詳細資訊，請參閱使用 MSBuild 建立 NuGet 套件。

注意

若要建立及發佈非 SDK 樣式專案的套件，通常是 .NET Framework 專案，請參閱使用 nuget.exe CLI 建立套件或使用 Visual Studio 建立和發佈套件（.NET Framework）。
對於從 packages.config 移轉至 PackageReference 的專案，請使用 msbuild -t:pack。如需詳細資訊，請參閱移轉后建立套件。

設定屬性

您可以使用命令建立範例類別庫專案 dotnet new classlib ，並使用封裝專案 dotnet pack。命令 dotnet pack 會使用下列屬性。如果您未在項目檔中指定值，命令會使用預設值。

PackageId、套件標識碼在裝載封裝的 nuget.org 和任何其他目標之間必須是唯一的。如果您未指定值，命令會 AssemblyName使用。
Version 是格式 Major.Minor.Patch[-Suffix]的特定版本號碼，其中 -Suffix 會識別發行前版本。如果未指定，預設值為 1.0.0。
Authors 是套件的作者。如果未指定，則預設值為 AssemblyName。
Company 是公司資訊。如果未指定，則預設值為 Authors 值。
Product 是產品資訊。如果未指定，則預設值為 AssemblyName。

在 Visual Studio 中，您可以在專案屬性中設定這些值。以滑鼠右鍵按兩下方案總管中的項目，選取 [屬性]，然後選取 [封裝] 區段。您也可以將屬性直接新增至 .csproj 或其他項目檔。

下列範例顯示已新增套件屬性的項目檔。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>UniqueID</PackageId>
    <Version>1.0.0</Version>
    <Authors>Author Name</Authors>
    <Company>Company Name</Company>
    <Product>Product Name</Product>
  </PropertyGroup>
</Project>

您可以新增其他選擇性屬性，例如 Title、 PackageDescription與 PackageTags。

注意

針對您為公用取用而建置的 PackageTags 套件，請特別注意屬性。標籤可協助其他人尋找您的套件，並瞭解其用途。

命令 dotnet pack 會自動將 PackageReference項目檔中的轉換成所建立套件中的相依性。您可以控制要透過 IncludeAssets、 ExcludeAssets 和 PrivateAssets 標記包含哪些資產。如需詳細資訊，請參閱控制相依性資產。

如需相依性、選擇性屬性和版本控制的詳細資訊，請參閱：

選擇唯一的套件識別碼並設定版本號碼

套件標識碼和版本號碼可唯一識別封裝中包含的確切程式代碼。

請遵循下列最佳做法來建立套件識別碼：

標識碼在裝載封裝的 nuget.org 和所有其他位置之間必須是唯一的。為了避免衝突，良好的模式是使用您的公司名稱作為標識符的第一個部分。
使用點表示法遵循類似 .NET 命名空間的命名慣例。例如，使用 Contoso.Utility.UsefulStuff，而非 Contoso-Utility-UsefulStuff 或 Contoso_Utility_UsefulStuff。如果您將套件識別碼與程式代碼所使用的命名空間相符，則對取用者也很有説明。
如果您產生示範如何使用另一個封裝的 範例程式代碼 套件，請附加 .Sample 至標識符，如中所示 Contoso.Utility.UsefulStuff.Sample。

範例套件與原始套件具有相依性。當您建立範例套件時，請使用 contentFiles 值來新增 <IncludeAssets> 。在內容資料夾中，將範例程式代碼排列在名為 \Samples\<identifier> 的資料夾，例如 \Samples\Contoso.Utility.UsefulStuff.Sample。

請遵循下列最佳做法來設定套件版本：

一般而言，將套件版本設定為 符合專案或元件版本，但並非絕對必要。當您將套件限制為單一元件時，比對版本很簡單。 NuGet 本身會在解析相依性時處理套件版本，而不是元件版本。
如果您使用非標準版本配置，請務必考慮 NuGet 版本控制規則，如套件版本控制中所述。 NuGet 大多符合語意版本設定 2.0.0 規範。

注意

如需相依性解析的詳細資訊，請參閱使用 PackageReference 的相依性解析。如需可能有助於瞭解版本設定的資訊，請參閱這一系列的部落格文章：

新增選擇性描述欄位

套件的選擇性描述會出現在 套件的 [nuget.org] 頁面的 [自述檔 ] 索引標籤上。描述會從<Description>項目檔或 $description .nuspec 檔案中的提取。

下列範例顯示在 Description .net 套件的 .csproj 檔案中：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <PackageId>Azure.Storage.Blobs</PackageId>
    <Version>12.4.0</Version>
    <PackageTags>Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable</PackageTags>
    <Description>
      This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data.
      For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md
      in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt
      Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/
      Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/
      REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api
    </Description>
  </PropertyGroup>
</Project>

執行 pack 命令

若要建置 NuGet 套件或 .nupkg 檔案，請從專案資料夾執行 dotnet pack 命令，這也會自動建置專案。

dotnet pack

輸出會顯示 .nupkg 檔案的路徑：

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms).
  Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'.

建置時自動產生套件

若要在每當您執行時自動執行 dotnet packdotnet build，請將下列這一行新增至標記中的 <PropertyGroup> 項目檔：

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

注意

當您自動產生套件時，封裝會增加專案的建置時間。

在方案套件上執行 dotnet pack ，會封裝方案中的所有專案，也就是將 IsPackable 屬性設定為 true。

測試套件安裝

發佈套件之前，您應該先測試將套件安裝到專案中。測試可確保必要的檔案最終出現在項目的正確位置。

使用一般套件安裝程式，在 Visual Studio 或命令行上手動測試安裝。

重要

一旦建立之後，就無法變更套件。如果您更正問題，請變更套件內容並重新封裝。
重新建立套件之後，重新測試仍會使用舊版的套件，直到您清除全域套件資料夾為止。清除資料夾對於未在每個組建上使用唯一發行前版本標籤的套件特別重要。

下一步

建立套件之後，您可以將 .nupkg 檔案發佈至您選擇的主機。

發行套件

如需擴充套件功能或支援其他案例的方式，請參閱下列文章：