快速入門：使用 dotnet CLI 建立和發佈套件

  • 發行項

本快速入門說明如何使用 .NET 命令行介面或 dotnet CLI，從 .NET 類別庫快速建立 NuGet 套件，並將其發佈至 nuget.org。

必要條件

  • .NET SDK，提供 dotnet 命令行工具。 從 Visual Studio 2017 開始，dotnet CLI 會自動安裝任何 .NET 或 .NET Core 相關工作負載。

  • nuget.org 的免費帳戶。請依照新增個別帳戶中的指示操作。

建立類別庫專案

您可以針對您要封裝的程式代碼使用現有的 .NET 類別庫專案，或建立簡單的專案，如下所示：

  1. 建立名為 AppLogger 的資料夾。
  2. 開啟命令提示字元並切換至 AppLogger 資料夾。 本快速入門中的所有 dotnet CLI 命令預設都會在目前資料夾上執行。
  3. 輸入 dotnet new classlib，這會建立具有目前資料夾名稱的專案。

如需詳細資訊，請參閱 dotnet new。

將套件中繼資料新增至專案檔

每個 NuGet 套件都有描述套件內容和相依性的指令清單。 在最終套件中，指令清單是 .nuspec 檔案，它會使用您在項目檔中包含的 NuGet 元數據屬性。

開啟 .csproj、.fproj 或 .vbproj 項目檔，並在現有<PropertyGroup>標記內新增下列屬性。 針對名稱和公司使用您自己的值，並將套件識別碼取代為唯一值。

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

重要

套件標識碼在 nuget.org 和其他套件來源之間必須是唯一的。 發佈會公開顯示套件，因此如果您使用範例 AppLogger 連結庫或其他測試連結庫，請使用包含 Sample 或 Test的唯一名稱。

您可以新增 NuGet 元資料屬性中所述 的任何選擇性屬性。

注意

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

執行 pack 命令

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

dotnet pack

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

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

建置時自動產生套件

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

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

發行套件

使用 dotnet nuget push 命令搭配您從 nuget.org 取得的 API 金鑰，將您的 .nupkg 檔案發佈至 nuget.org。

注意

  • Nuget.org 掃描所有上傳的套件是否有病毒，並在找到任何病毒時拒絕套件。 Nuget.org 也會定期掃描所有現有的列出的套件。

  • 除非取消列出套件，否則您發行至 nuget.org 的套件會公開顯示給其他開發人員。 若要私下裝載套件，請參閱 裝載您自己的 NuGet 摘要。

取得 API 金鑰

  1. 登入您的 nuget.org 帳戶，或如果您還沒有帳戶，請建立帳戶。

  2. 選取右上方的使用者名稱，然後選取 [API 金鑰]。

  3. 選取 [ 建立]，並提供密鑰的名稱。

  4. 在 [選取範圍] 下，選取 [推送]。

  5. 在 [選取套件>Glob 模式] 下，輸入 *。

  6. 選取 建立。

  7. 選取 [ 複製 ] 以複製新的金鑰。

    Screenshot that shows the new API key with the Copy link.

重要

  • 一律將您的 API 金鑰保密。 API 金鑰就像是一種密碼，可讓任何人代表您管理套件。 如果不小心顯示 API 金鑰，請刪除或重新產生您的 API 金鑰。
  • 將您的金鑰儲存在安全的位置，因為您稍後無法再次複製金鑰。 如果您返回 API 金鑰頁面，則需要重新產生金鑰才能加以複製。 如果您不想再推送套件，您也可以移除 API 金鑰。

範圍可讓您針對不同的用途建立個別的 API 金鑰。 每個金鑰都有到期時間範圍，您可以將金鑰範圍設定為特定套件或 glob 模式。 您也會將每個金鑰的範圍設定為特定作業：推送新的套件和套件版本、只推送新的套件版本，或取消列出。

透過範圍界定，您可以為管理組織套件的不同人員建立 API 金鑰，讓他們只擁有所需的許可權。

如需詳細資訊，請參閱限定範圍的 API 金鑰。

使用 dotnet nuget push 發行

從包含 .nupkg 檔案的資料夾，執行下列命令。 指定 . nupkg 檔名，並將密鑰值取代為您的 API 金鑰。

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

輸出會顯示發佈程序的結果：

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

如需詳細資訊，請參閱 dotnet nuget push。

注意

如果您想要避免在 nuget.org 上即時測試套件，您可以在 推送至 nuget.org 測試網站 https://int.nugettest.org。請注意，上傳至 int.nugettest.org 的套件可能不會保留。

發行錯誤

來自 push 命令的錯誤通常代表發生問題。 例如，您可能忘記更新專案中的版本號碼，因此您正嘗試發佈已經存在的套件。

如果您 API 金鑰無效或已過期，或嘗試使用主機上已存在的識別碼發佈套件，您也會看到錯誤。 例如，假設標識碼 AppLogger-test 已存在於 nuget.org 上。如果您嘗試發行具有該識別碼的套件， push 命令會提供下列錯誤：

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

如果您收到此錯誤，請檢查您使用的是尚未過期的有效 API 金鑰。 如果您這麼做，錯誤表示主機上已經有封裝標識碼。 若要修正錯誤，請將套件標識符變更為唯一、重建專案、重新建立 .nupkg 檔案，然後重試 push 命令。

管理已發行的套件

當您的套件成功發佈時，您會收到確認電子郵件。 若要查看您剛發佈的套件，請在 nuget.org 上選取您的使用者名稱，然後選取 [管理套件]。

注意

您的套件可能需要一些時間才能編製索引，並出現在其他人可以找到它的搜尋結果中。 在此期間，您的套件會出現在 [未列出的套件] 底下，而套件頁面會顯示下列訊息：

Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.

您現在已將 NuGet 套件發佈至 nuget.org 其他開發人員可以在其專案中使用。

如果您已建立的套件並無用處（例如這個以空類別庫建立的範例套件），或您決定不想要顯示套件，您可以將 套件取消列出 ，使其從搜尋結果中隱藏：

  1. 套件出現在 [管理套件] 頁面上的 [已發佈套件] 底下之後，選取套件清單旁的鉛筆圖示。

    Screenshot that shows the Edit icon for a package listing on nuget.org.

  2. 在下一個頁面上，選取 [列出]，取消選取 搜尋結果 中的 [清單] 複選框，然後選取 [ 儲存]。

    Screenshot that shows clearing the List checkbox for a package on nuget.org.

套件現在會出現在 [管理套件] 中的 [未列出的套件] 底下，且不再出現在搜尋結果中。

注意

若要避免在 nuget.org 上執行測試套件，您可以在 上推送至 nuget.org 測試網站 https://int.nugettest.org。請注意，上傳至 int.nugettest.org 的套件可能不會保留。

恭喜您建立和發佈您的第一個 NuGet 套件！

在 Channel 9 和 YouTube 上尋找更多 NuGet 影片。

下一步

如需如何使用 dotnet CLI 建立套件的詳細資訊：

使用 dotnet CLI 建立 NuGet 套件

取得建立和發佈 NuGet 套件的詳細資訊：