使用 MSBuild 建立 NuGet 套件

發行項
12/14/2023

當您從程式碼建立 NuGet 套件時，會將該功能封裝至可由任意數目的其他開發人員共用和使用的元件。本文說明如何使用 MSBuild 建立套件。 MSBuild 會使用每個包含 NuGet 的 Visual Studio 工作負載來進行預先安裝。此外，您也可以透過 dotnet CLI 搭配 dotnet msbuild 使用 MSBuild。

針對使用 SDK 樣式格式與任何其他 SDK 樣式專案的 .NET Core 與 .NET Standard 專案，NuGet 會直接使用專案檔中的資訊來建立套件。針對使用 <PackageReference> 的非 SDK 樣式專案，NuGet 也會使用專案檔來建立套件。

SDK 樣式的專案預設會提供套件功能。針對非 SDK 樣式的 PackageReference 專案，您必須將 NuGet.Build.Tasks.Pack 套件新增至專案相依性。如需 MSBuild 套件目標的詳細資訊，請參閱 NuGet 套件和還原為 MSBuild 目標。

建立封裝 msbuild -t:pack的指令在功能上相當於 dotnet pack。

重要

本主題適用於 SDK 樣式的專案 (通常是 .NET Core 和 .NET Standard 專案)，以及適用於使用 PackageReference 的非 SDK 樣式專案。

設定屬性

建立套件時需要下列屬性。

PackageId，套件識別碼，這在裝載套件的資源庫內必須是唯一的。如果未指定，預設值為 AssemblyName。
Version，Major.Minor.Patch[-Suffix] 形式的特定版本號碼，其中 -Suffix 識別發行前版本。若未指定，則預設值為 1.0.0。
主機上應該會出現套件標題 (例如 nuget.org)
Authors，作者與擁有者資訊。如果未指定，預設值為 AssemblyName。
Company，您的公司名稱。如果未指定，預設值為 AssemblyName。

此外，如果您要封裝使用 PackageReference 的非 SDK 樣式專案，則需要下列專案：

PackageOutputPath，呼叫Pack時所產生封裝的輸出資料夾。

在 Visual Studio 中，您可以在專案屬性中設定這些值 (在 [方案總管] 中以滑鼠右鍵按一下專案，選擇 [屬性]，然後選取 [套件] 索引標籤)。您也可以直接在專案檔 (.csproj) 中設定這些屬性。

<PropertyGroup>
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>your_name</Authors>
  <Company>your_company</Company>
</PropertyGroup>

重要

為套件指定識別碼，此識別碼在 nuget.org 上或您使用的任何套件資源上都必須是唯一的。

下列範例顯示一個簡單且完整的專案檔，其中會包含這些屬性。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Version>1.0.0</Version>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
  </PropertyGroup>
</Project>

您還可以設定選擇性屬性，例如Title、PackageDescription 與 PackageTags，如 MSBuild 套件目標、控制相依性資產，以及 NuGet 中繼資料屬性中所述。

注意

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

如需宣告相依性及指定版本號碼的詳細資料，請參閱專案檔中的套件參考和套件版本控制。使用 <IncludeAssets> 與 <ExcludeAssets> 屬性，也可以將來自相依性的資產直接用於套件中。如需詳細資訊，請參閱控制相依性資產。

新增選擇性描述欄位

套件的選擇性描述會出現在 套件的 [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>

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

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

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

標識碼在裝載封裝的 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.Build.Tasks.Pack 套件

如果您使用 MSBuild 搭配非 SDK 樣式的專案和 PackageReference，請將 NuGet.Build.Tasks.Pack 套件新增至您的專案。

開啟專案檔，並在 <PropertyGroup> 元素之後新增下列內容：

<ItemGroup>
  <!-- ... -->
  <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.7.0" PrivateAssets="all" />
  <!-- ... -->
</ItemGroup>

注意

請考慮使用此套件的最新版本。

開啟開發人員命令提示字元 (在 [搜尋] 方塊中，輸入開發人員命令提示字元)。

您通常想要從 [開始] 功能表啟動適用於 Visual Studio 的開發人員命令提示字元，因為它將使用適用於 MSBuild 的所有必要路徑來設定。
切換至包含專案檔的資料夾，並輸入下列命令以安裝 NuGet.Build.Tasks.Pack 套件。
```
# Uses the project file in the current folder by default
msbuild -t:restore
```
確定 MSBuild 輸出會指出組建已順利完成。

執行 msbuild -t:pack 命令

若要從專案建置 NuGet 套件 (.nupkg 檔案)，請執行 msbuild -t:pack 命令，該命令也會自動建置專案：

在 Visual Studio 開發人員命令提示字元中，輸入下列命令：

# Uses the project file in the current folder by default
msbuild -t:pack

輸出將顯示 .nupkg 檔案的路徑。

Microsoft (R) Build Engine version 16.1.76+g14b0a930a7 for .NET Framework
Copyright (C) Microsoft Corporation. All rights reserved.

Build started 8/5/2019 3:09:15 PM.
Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" on node 1 (pack target(s)).
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  ...
CopyFilesToOutputDirectory:
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.dll" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll".
  ClassLib_DotNetStandard -> C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.dll
  Copying file from "C:\Users\username\source\repos\ClassLib_DotNetStandard\obj\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb" to "C:\Use
  rs\username\source\repos\ClassLib_DotNetStandard\bin\Debug\netstandard2.0\ClassLib_DotNetStandard.pdb".
GenerateNuspec:
  Successfully created package 'C:\Users\username\source\repos\ClassLib_DotNetStandard\bin\Debug\AppLogger.1.0.0.nupkg'.
Done Building Project "C:\Users\username\source\repos\ClassLib_DotNetStandard\ClassLib_DotNetStandard.csproj" (pack target(s)).

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:01.21

建置時自動產生套件

若要在您建置或還原專案時自動執行 msbuild -t:pack，請將下一行新增至專案檔的 <PropertyGroup> 中：

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

當您在解決方案上執行 msbuild -t:pack 時，這會封裝解決方案中可封裝的所有專案 (<IsPackable> 屬性會設定為 true)。

注意

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

測試套件安裝

發行套件之前，您通常會想要測試將套件安裝至專案的程序。測試可確定必要檔案最後都在專案的正確位置。

您可以使用一般套件安裝步驟，以在 Visual Studio 中或命令列上手動測試安裝。

重要

套件是不可變的。如果您更正了問題，請變更套件的內容並再次封裝，當您重新測試時，仍會使用舊版套件，直到您清除全域套件資料夾為止。在測試每個組建上未使用唯一發行前版本標籤的套件時，這關係重大。

後續步驟

建立套件 (即 .nupkg 檔案) 之後，即可將它發行至您選擇的資源庫，如發行套件中所述。

您也可能想要擴充您套件的功能，或支援其他案例，如下列各主題中所述：

最後，請注意其他套件類型：

共用方式為