快速入門:使用 Visual Studio 建立及發佈 NuGet 套件(僅限 Windows)

透過 Microsoft Visual Studio,您可以從 .NET 類別庫建立 NuGet 套件,然後使用 CLI 工具將其發佈至 nuget.org。

快速入門僅適用於 Windows 使用者。 如果您使用 Visual Studio for Mac,請參閱 從現有的連結庫專案 建立 NuGet 套件或使用 .NET CLI

必要條件

  • 使用 .NET Core 相關工作負載安裝 Visual Studio 2022 for Windows。

    您可以從 visualstudio.microsoft.com 免費安裝 2022 Community 版本,或使用 Professional 或 Enterprise 版本。

    當您安裝 時,Visual Studio 2017 和更新版本會自動包含 NuGet 功能。與 NET 相關的工作負載。

  • 如果尚未安裝 .NET CLI,請加以安裝。

    針對 Visual Studio 2017 和更新版本,.NET CLI 會自動隨任何 .NET Core 相關工作負載一起安裝。 否則,請安裝 .NET Core SDK 以取得 .NET CLI。 使用 SDK 樣式格式 (SDK 屬性) 的 .NET 專案需要 .NET CLI。 Visual Studio 2017 和更新版本中的預設 .NET 類別庫範本會使用 SDK 屬性。

    重要

    如果您使用非 SDK 樣式的專案,請遵循建立和發佈 .NET Framework 套件 (Visual Studio) 中的程式,改為建立及發佈套件。 在本文中,建議使用 .NET CLI。 雖然您可以使用 NuGet CLI 發佈任何 NuGet 套件,但本文中的一些步驟是 SDK 樣式專案和 .NET CLI 特有的。 NuGet CLI 用於 非 SDK 樣式專案 (通常是 .NET Framework)。

  • 如果您還沒有帳戶,請在 nuget.org 上註冊一個免費帳戶 \(英文\)。 您必須先註冊並確認帳戶,才能上傳 NuGet 套件。

  • nuget.org 下載 NuGet CLI 來安裝它。將 nuget.exe 檔案新增至適當的資料夾,並將該資料夾新增至您的PATH環境變數。

建立類別庫專案

您可以針對您要封裝的程式代碼使用現有的 .NET 類別庫專案,或建立一個專案,如下所示:

  1. 在 Visual Studio 中,選取 [檔案]>[新增]>[專案]

  2. 在 [ 建立新專案 ] 視窗中,選取 下拉式清單中的 C#Windows[連結庫 ]。

  3. 在產生的專案範本清單中,選取 [類別庫 ] (描述為 建立以 .NET 或 .NET Standard 為目標的類別庫的專案],然後選取 [下一步]。

  4. 在 [設定您的新專案] 視窗中,輸入 AppLogger 以取得 [專案名稱],然後選取 [下一步]。

  5. 在 [ 其他資訊] 視窗中,選取適當的 Framework,然後選取 [ 建立]。

    如果您不確定要選取哪一個架構,最新的是不錯的選擇,而且稍後很容易變更。 如需要使用哪一個架構的資訊,請參閱 何時以 .NET 5.0 或 .NET 6.0 與 .NET Standard 為目標

  6. 若要確保專案已正確建立,請選取 [>置建置方案]。 DLL 位於 Debug 資料夾 (如果您改為建置該組態則為 Release)。

  7. (選擇性)在本快速入門中,您不需要為 NuGet 套件撰寫任何其他程式碼,因為範本類別庫足以建立套件。 不過,如果您想要套件的一些功能程式碼,請包含下列程式代碼:

    namespace AppLogger
    {
        public class Logger
        {
            public void Log(string text)
            {
                Console.WriteLine(text);
            }
        }
    }
    

設定套件屬性

建立項目之後,您可以遵循下列步驟來設定 NuGet 套件屬性:

  1. 在 方案總管 中選取您的專案,然後選取 [項目><專案名稱>屬性],其中<專案名稱>是您項目的名稱。

  2. 展開 [ 套件] 節點,然後選取 [ 一般]。

    套件節點只會針對 Visual Studio 中的 SDK 樣式項目顯示。 如果您的目標是非 SDK 樣式專案(通常是 .NET Framework),請 移轉專案,或參閱 建立及發佈 .NET Framework 套件 以取得逐步指示。

    Screenshot showing NuGet package properties in a Visual Studio project.

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

  4. 為您的套件提供唯 一的套件標識碼 ,並填寫任何其他所需的屬性。 如需顯示 MSBuild 屬性 (SDK 樣式專案) 如何對應至 .nuspec 檔案屬性的數據表,請參閱 套件目標。 如需 .nuspec 檔案屬性的描述,請參閱 .nuspec 檔案參考。 所有這些屬性都會進入 .nuspec Visual Studio 為專案建立的指令清單。

    重要

    您必須為套件指定識別碼,此識別碼在 nuget.org 上或您使用的任何主機上都必須是唯一的。 否則,會發生錯誤。 在本快速入門中,建議您在 名稱中包含SampleTest ,因為發佈步驟會公開顯示套件。

  5. (選擇性)若要直接在 AppLogger.csproj 專案檔中查看屬性,請選取 [專案>編輯項目檔]。

    AppLogger.csproj 索引標籤會載入。

    此選項從 Visual Studio 2017 開始提供,適用於使用 SDK 樣式屬性的專案。 針對舊版 Visual Studio,您必須先選取 [專案>卸除專案],才能編輯項目檔。

執行 pack 命令

若要從您的專案建立 NuGet 套件,請遵循下列步驟:

  1. 選取 [建置>組態管理員],然後將 [作用中方案組態] 設定為 [發行]。

  2. 選取 方案總管 中的 AppLogger 專案,然後選取 [套件]。

    Visual Studio 會建置專案並建立 .nupkg 檔案。

  3. 檢查 [ 輸出 ] 視窗以取得詳細數據,其中包含封裝檔案的路徑。 在此範例中,建置元件位於 bin\Release\net6.0 中,適合 .NET 6.0 目標:

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
    1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
    1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
    ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
    
  4. 如果您沒有在功能表上看到 Pack 命令,您的專案可能不是SDK樣式專案,而且需要使用NuGet CLI。 移轉專案並使用 .NET CLI,或如需逐步指示,請參閱建立及發佈 .NET Framework 套件

(選擇性) 建置時產生套件

您可以在建置專案時,將 Visual Studio 設定為自動產生 NuGet 套件:

  1. 在 方案總管 中選取您的專案,然後選取 [專案<>名稱>屬性],其中<專案名稱是專案的名稱>(在此案例中為 AppLogger)。

  2. 展開 [套件] 節點,選取 [一般],然後選取 [建置時產生 NuGet 套件]。

    Screenshot showing package properties with Generate NuGet package on build selected.

注意

當您自動產生套件時,套件的額外時間會增加項目的整體建置時間。

(選擇性)使用 MSBuild 封裝

除了使用 [套件 ] 功能表命令,NuGet 4.x+ 和 MSBuild 15.1+ 支援 pack 當專案包含必要套件數據時的目標:

  1. 在 方案總管 中開啟專案時,選取 [工具>命令行>開發人員命令提示字元] 來開啟命令提示字元。

    命令提示字元會在您的專案目錄中開啟。

  2. 執行下列命令:msbuild -t:pack

如需詳細資訊,請參閱使用 MSBuild 建立套件

發行套件

建立 .nupkg 檔案之後,請使用 .NET CLI 或 NuGet CLI,以及從 nuget.org 取得的 API 密鑰,將其發行至 nuget.org。

注意

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

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

取得 API 金鑰

發佈 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 金鑰

使用 .NET CLI 或 NuGet CLI 發佈

下列每個 CLI 工具都可讓您將套件推送至伺服器並加以發佈。 選取 CLI 工具的索引標籤: .NET CLINuGet CLI

使用 .NET CLI (dotnet.exe) 是使用 NuGet CLI 的建議替代方案。

從包含 .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 的套件可能不會保留。

新增自述檔或其他檔案

若要直接指定要包含在封裝中的檔案,請編輯項目檔並新增 content 屬性:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

在此範例中,屬性會指定專案根目錄中名為 readme.txt 的檔案。 Visual Studio 會在安裝套件之後,立即以純文本顯示該檔案的內容。 不會針對安裝為相依性的套件顯示自述檔。 例如,以下是 HtmlAgilityPack 套件的自述檔:

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. 
7 This is normally found at 
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client 
9 or 
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. 
14 This is normally found at 
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client 
16 or 
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

注意

如果您只將readme.txt新增到專案根目錄,而不將它content包含在專案檔的屬性中,它就不會包含在封裝中。

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

恭喜使用 Visual Studio .NET 類別庫建立 NuGet 套件。 請前進到下一篇文章,瞭解如何使用Visual Studio.NET Framework 建立 NuGet 套件。

若要探索 NuGet 必須提供的詳細資訊,請參閱下列文章: