共用方式為


使用 MSBuild 建立 NuGet 套件

當您從程式碼建立 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
  • VersionMajor.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>

您還可以設定選擇性屬性,例如TitlePackageDescriptionPackageTags,如 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-UsefulStuffContoso_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 套件新增至您的專案。

  1. 開啟專案檔,並在 <PropertyGroup> 元素之後新增下列內容:

    <ItemGroup>
      <!-- ... -->
      <PackageReference Include="NuGet.Build.Tasks.Pack" Version="6.7.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 檔案) 之後,即可將它發行至您選擇的資源庫,如發行套件中所述。

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

最後,請注意其他套件類型: