共用方式為

使用 MSBuild 建立 NuGet 套件

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

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

SDK 樣式專案預設具有可用的套件功能。 對於非 SDK 樣式的 PackageReference 專案，從 Visual Studio 2026 開始預設也可用。 在舊版的 Visual Studio 中，您必須將 NuGet.Build.Tasks.Pack 套件新增至專案相依性，建議您在升級至 Visual Studio 2026 時移除此套件參考。 如需 MSBuild 套件目標的詳細資訊，請參閱 NuGet 套件並還原為 MSBuild 目標。

對於 SDK 樣式的專案， 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 頁面上的 README 標籤頁上。 描述會從專案檔中的 <Description> 或 $description.nuspec 檔中的 提取。

下列範例顯示 .NET 套件的 Description 檔案中的 a：

<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所示。

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

請遵循下列最佳實務來設定套件版本：

  • 一般而言，請將套件版本設定 為符合專案或元件版本，但這並非絕對必要。 當您將封裝限制為單一組件時，比對版本很簡單。 NuGet 本身會在解析相依性時處理套件版本，而不是元件版本。

  • 如果您使用非標準版本配置，請務必考慮 NuGet 版本設定規則 ，如 套件版本設定中所述。 NuGet 大多符合 語意版本設定 2.0.0 規範。

備註

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

為打包設定專案

SDK 樣式的專案不需要任何額外的設定。

非 SDK 樣式的專案需要至少安裝一個套件 （透過 PackageReference，而不是 packages.config），或專案需要明確指示 NuGet 透過屬性將 RestoreProjectStyle 專案視為 PackageReference 專案。

Visual Studio 2022 和更早版本沒有內建套件，因此您也必須安裝 NuGet.Build.Tasks.Pack 套件。 升級至 Visual Studio 2026 或更新版本時，建議您解除安裝套件，以便受益於新功能和錯誤修正。

  1. 編輯專案檔案。

    如果您想要明確指示 NuGet 將專案視為 PackageReference（該專案未安裝任何套件），請尋找或新增一個不包含任何 <PropertyGroup> 陳述式的 Condition，然後新增：

    <PropertyGroup>
  <!-- other properties -->
  <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
  <!-- more properties are allowed -->
</PropertyGroup>

    如果您使用的是 Visual Studio 2022 或更早的版本，請在 <PropertyGroup> 元素後新增以下項目：

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

    備註

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

  2. 開啟開發人員命令提示字元 （在 [ 搜尋 ] 方塊中，輸入 開發人員命令提示字元）。

    您通常會從 [開始] 功能表中啟動 Visual Studio 的開發人員命令提示符，因為它已配置所有必需的 MSBuild 路徑。

  3. 切換至包含專案檔案的資料夾，然後輸入下列命令來還原 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 檔案） 之後，您可以將它發佈至您選擇的資源庫，如 發佈套件中所述。

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

最後，還有其他套件類型需要注意：

  • Last updated on