快速入門：使用 Visual Studio 建立及發行套件 (.NET Framework，Windows)

  • 發行項

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

快速入門僅適用於 Windows 使用者。 如果您使用 Visual Studio for Mac，請參閱 dotnet CLI 工具 。

必要條件

  • 使用任何 安裝Visual Studio 2022 for Windows。與 NET 相關的工作負載。

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

    安裝 .NET 工作負載時，Visual Studio 2017 和更新版本會自動包含 NuGet 功能。

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

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

建立類別庫專案

若要建立類別庫專案，請遵循下列步驟：

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

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

  3. 在產生的專案範本清單中，選取 [類別庫][.NET Framework]，然後選取 [ 下一步]。

  4. 在 [設定您的新專案] 視窗中，輸入 AppLogger 以取得 [專案名稱]，然後選取 [建立]。

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

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

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

    在真實世界的 NuGet 套件中，您可能會實作許多實用的功能，讓其他人可以建置應用程式。 您也可以設定目標架構。 如需範例，請參閱 UWP 和 Xamarin。

為套件設定專案屬性

NuGet 套件包含指令清單（檔案 .nuspec ），其中包含相關的元數據，例如套件標識碼、版本號碼、描述等等。 有些元數據可以直接從專案屬性中繪製，以避免在專案和指令清單中分別更新它們。 下列步驟說明如何設定適用的屬性：

  1. 選取 [項目 > 屬性]，然後選取 [ 應用程式] 索引 標籤。

  2. 針對 元件名稱，為您的套件提供唯一標識符。 如果您嘗試發行名稱已經存在的套件，則會看到錯誤。

    重要

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

  3. 選取 [元件資訊]，其中顯示一個對話框，您可以在其中輸入攜帶指令清單的其他屬性（請參閱 取代令牌）。 最常使用的欄位是標題、描述、公司、著作權 和 組件版本。 由於這些屬性會在發佈之後，您的套件出現在主機上，例如 nuget.org，因此請確定它們具有完整描述性。

    Screenshot showing the Assembly Information page in a .NET Framework project in Visual Studio.

  4. （選擇性）若要直接查看和編輯屬性，請選取 [專案>編輯項目檔]，以開啟專案中的屬性/AssemblyInfo.cs檔案。

  5. 設定這些屬性之後，請將 [建>置組態管理員] 中的 [使用中方案組態] 設定為 [發行]，然後重建專案以產生更新的 DLL。

產生初始資訊清單

設定項目屬性並建立 DLL 之後，您現在可以從項目產生初始 .nuspec 檔案。 這個步驟包含了相關的取代權杖，以從專案檔中取出資訊。

只執行 nuget spec 一次以產生初始指令清單。 如果您更新封裝，請變更專案中的值，或直接編輯指令清單：

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

    命令提示字元會在檔案所在的 AppLogger.csproj 項目目錄中開啟。

  2. 執行下列命令：nuget spec AppLogger.csproj

    NuGet 會建立符合項目名稱的指令清單，在此案例中為 AppLogger.nuspec。 它也會在指令清單中包含取代令牌。

  3. 在文字編輯器中開啟 AppLogger.nuspec 以檢查其內容，這類似於下列程式代碼：

    <?xml version="1.0"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Your username</authors>
    <owners>Your username</owners>
    <license type="expression">MIT</license>
    <!-- <icon>icon.png</icon> -->
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

編輯資訊清單

  1. 繼續之前，請先編輯下列屬性。 否則，如果您嘗試使用檔案 .nuspec 中的預設值建立 NuGet 套件，就會發生錯誤。 如需這些屬性的相關信息，請參閱 選擇性元數據元素：

    • licenseUrl
    • projectUrl
    • releaseNotes
    • 標記

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

  3. 您也可以目前將任何其他元素新增至指令清單，如 .nuspec 檔案參考中所述。

  4. 儲存檔案後再繼續。

執行 pack 命令

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

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

  2. 執行下列命令：nuget pack

    NuGet 會以目前資料夾中的 identifier.version.nupkg 格式產生 .nupkg 檔案。

發行套件

建立 .nupkg 檔案之後，請使用 NuGet CLI 搭配從 nuget.org 取得的 API 密鑰，將其發佈至 nuget.org。針對 nuget.org，您必須使用 nuget.exe 4.1.0 或更高版本。

如果您想要在發佈套件至公用資源庫之前先測試並驗證套件，您可以將它上傳至測試環境，例如 int.nugettest.org ，而不是 nuget.org。請注意，上傳至 int.nugettest.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 金鑰。

使用 NuGet CLI 發佈

使用 NuGet CLI （nuget.exe） 是使用 .NET CLI 的替代方案：

  1. 開啟命令提示字元，並變更為包含 .nupkg 檔案的資料夾。

  2. 執行下列命令。 以套件的檔名取代 <套件檔名> ，並以您的 API 金鑰取代 <API 金鑰值> 。 套件檔名是套件標識碼和版本號碼的串連，擴展名為 .nupkg 。 例如， AppLogger.1.0.0.nupkg：

    nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json

    發佈程式的結果如下所示：

    Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
    PUT https://www.nuget.org/api/v2/package/
    Created https://www.nuget.org/api/v2/package/ 6829ms
Your package was pushed.

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

發行錯誤

來自 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 的套件可能不會保留。

下一步

恭喜使用 Visual Studio .NET Framework 建立 NuGet 套件。 前進到下一篇文章，瞭解如何使用 NuGet CLI 建立 NuGet 套件。

使用 NuGet CLI 建立套件

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