套件撰寫最佳做法
本指南旨在為 NuGet 套件作者提供輕量型參考，以建立和發佈高品質的套件。 它主要著重於套件特定的最佳做法，例如元數據和封裝。 如需建置高質量連結庫的更深入建議，請參閱 .NET 開放原始碼連結庫指引。
建議類型
每篇文章都呈現四種類型的建議：優先、考慮、避免與禁止。 建議的類型會指出應該遵循的建議程度。
您應該一律遵循優先類型的建議。 例如：
✔️ 請包含套件的簡短描述，以描述其用途。
另一方面， 考慮 建議通常應該遵循，但規則有合法的例外狀況：
✔️ 請考慮選擇具有符合 NuGet 前置詞保留 準則的 NuGet 套件名稱。
避免建議指的是通常不建議採行的建議，但有時違反規則尚屬合理情況：
❌ 避免要求明確版本的 NuGet 套件參考。
最後，禁止類型的建議表示在多數情況下都不應採取的動作：
❌ 請勿使用 LicenseUrl 元數據屬性。
建立 NuGet 套件
建立 NuGet 套件的最新建議方式是來自 SDK 樣式的專案。 SDK 樣式的項目屬性，包括目標 Framework 和套件元數據，都是在專案檔中定義。
在 Visual Studio 或 dotnet CLI 中定義必要的屬性和封裝，以從 SDK 樣式專案建立套件。
✔️ 請建立 SDK 樣式專案，並使用 Visual Studio 或 dotnet CLI 建立您的套件（pack）。
如需有關套件建立的詳細指引，包括必要的用戶端工具、專案檔範例和命令，請參閱 使用 dotnet CLI 建立 NuGet 套件。
若要協助決定要以哪個 .NET Framework 為目標，請參閱我們 針對跨平台目標的最新指引。
套件中繼資料
元數據是任何 NuGet 套件的基礎元件。 元數據的品質可能會大幅影響套件的可探索性、可用性和可信度。
在 Visual Studio 中，指定套件元數據的建議方式是移至 [專案 > 名稱] 屬性 > 套件。
您也可以 直接在項目檔中指定套件元資料元素。
以下是數據表對應，並描述可用的套件元數據元素：
| Visual Studio 屬性名稱 | 項目檔/ MSBuild 屬性名稱 | Nuspec 屬性名稱 | 描述 |
|---|---|---|---|
Package id |
PackageId |
id |
套件名稱或識別碼。 |
Package version |
PackageVersion |
version |
NuGet 套件版本。 |
Authors |
Authors |
authors |
以逗號分隔的套件作者清單，通常會使用個人的 或組織的「相當名稱」。 |
Description |
Description |
description |
套件的描述。 |
Copyright |
Copyright |
copyright |
套件的著作權詳細資料。 |
Project URL |
PackageProjectUrl |
projectUrl |
專案首頁的 URL。 |
Icon File |
PackageIcon |
icon |
封裝圖示圖像檔的路徑。 |
README |
PackageReadmeFile |
readme |
套件 README Markdown 檔案的路徑。 |
Repository URL |
RepositoryUrl |
repository url |
建置套件的來源存放庫 URL。 |
Repository type |
RepositoryType |
repository type |
存放庫 URL 指向的存放庫類型（也就是 “git” ）。 |
Tags |
PackageTags |
tags |
以空格分隔的標記與關鍵字清單，能描述套件。 標記會在搜尋套件時使用。 |
Release notes |
PackageReleaseNotes |
releaseNotes |
此套件版本中所做的變更描述。 |
Licensing - Expression |
PackageLicenseExpression |
license type="expression" |
SPDX 授權表達式。 |
Licensing - File |
PackageLicenseFile |
license type="file" |
自訂授權檔案的路徑。 |
封裝識別碼
如果您要發佈全新的套件：
✔️ DO 選擇唯一且清楚區分 NuGet.org 上現有套件的套件識別碼。
您可以藉由搜尋 NuGet.org 上的標識符，或檢查下列連結是否存在，來檢查套件識別碼是否是唯一且可區分的： https://www.nuget.org/packages/<套件名稱>。
✔️ 請考慮選擇具有符合 NuGet 前置詞保留準則的 NuGet 套件名稱。
保留套件的前置詞識別碼可讓您取得已驗證的複選標記：
請參閱 套件標識碼前置詞保留檔 以深入瞭解。
封裝版本
✔️ 請考慮使用 SemVer 來為您的 NuGet 套件建立版本。
基本上，這表示使用 Major.Minor.Patch[-prerelease] 格式。
✔️ 如果套件不穩定或預覽，請發行套件為 發行前版本套件 。
如需更進階的指引，請參閱 .NET 連結 庫版本控制指南 。
Authors
✔️ 請針對您或貴組織的「相當名稱」使用作者欄位。
例如，如果我的 NuGet.org 用戶名稱是 「jdoe」，則針對作者字段使用 「Jane Doe」 可能有助於取用者將我辨識為作者。 如果我組織的 NuGet.org 用戶名稱是 「ContosoToolkit」，則使用 「Contoso Corporation」 可能會更容易辨識並激發更多消費者的信任。
描述
✔️ 請包含簡短描述（最多 4000 個字元）來描述您的套件。
套件描述是 NuGet 搜尋中呈現的最突出欄位之一，而且可能是潛在取用者查看的第一件事，以判斷套件是否適合它們。
著作權
✔️ 請將著作權聲明新增至您的套件，其中包含「著作權（c） <名稱/公司><年度>」。
著作權聲明基本上表示，未經您的許可，無法複製您的作品。 在您的套件中包含著作權聲明很容易，不會造成任何傷害！
範例：Copyright （c） Contoso 2020
專案 URL
✔️ DO 包含相關聯專案、存放庫或公司網站的連結。
您的專案網站應該擁有用戶對於套件所需的一切資訊，而且可能是使用者尋找檔的位置。
Icon
✔️ 請考慮 在套件 中包含圖示，以協助以可視化方式區分它。 這是一個相對較小的補充，可以改善對套件品質的感知。
圖示可以專屬於個別套件或品牌標誌。
✔️ DO 使用 128x128 且具有透明背景 （PNG） 的影像，以獲得最佳檢視結果。
NuGet 會自動將您的影像縮放至所顯示的用戶端。
❌ 請勿使用已被取代的 IconUrl 元數據屬性。
讀我檔案
✔️ DO 新增 README Markdown 檔案 ，提供套件執行作業的概觀，以及如何開始使用。
套件自述檔可大幅改善套件的品質感知，以及新的用戶上線。 也請考慮 在上傳自述檔之前先預覽您的自述檔 ！ 如需詳細資訊，請參閱 如何在 NuGet 套件 中包含自述檔。
存放庫類型和URL
✔️ 請考慮設定 來源連結 ，將原始檔控制元數據自動新增至 NuGet 套件，並讓您的連結庫更容易進行偵錯。
來源鏈接會自動將 和
Repository Type新增Repository URL至套件元數據。 它也會新增與您的套件版本相關聯的特定認可。
標籤
✔️ DO 包含數個標記，其中包含與套件相關的重要詞彙，以增強可探索性。
標記會在 NuGet.org 的搜尋演算法中納入考慮，對於不在套件標識碼中，但相關詞彙特別有用。
例如，如果我將套件發佈至主控台記錄字串，我會包括：「記錄、記錄、主控台、字串、輸出」
版本資訊
✔️ DO 包含每個更新的版本資訊，說明所做的變更。
雖然版本資訊不需要特定格式，但我們建議包括：
- 重大變更
- 新功能
- 錯誤修正
如果您已經追蹤存放庫中的版本資訊或變更記錄，您也可以包含相關檔案的連結。
授權
✔️ 請在 您的套件中包含授權表達式或授權檔案。
重要
沒有授權的專案預設為 獨佔著作權，這表示您尚未授與任何人使用項目的許可權。
❌ 請勿使用已被取代的 LicenseUrl 元數據屬性。
當 URL 上的授權變更會追溯變更舊版套件的顯示授權時，這會呈現合法的模棱兩可。
如果您的套件是 開放原始碼
✔️ 請選擇 開放原始碼 授權，讓您的套件 開放原始碼。
「開放原始碼授權是符合開放原始碼定義的授權，簡言之，它們可讓軟體自由使用、修改及共用。 - 開放原始碼計劃。 若要深入瞭解 開放原始碼 軟體和開放原始碼計劃，請參閱 https://opensource.org/。
✔️ 請考慮 在您的套件中包含授權表達式。
授權表達式最清楚呈現，如果取用者可以使用您的套件，或授權已變更，則讓取用者更加清楚。
注意
NuGet.org 只接受開放原始碼方案或免費軟體基礎所核准授權的授權表達式。
如果您的套件未 開放原始碼
✔️ 請將 授權檔案包含在您的套件中。
任何授權檔案 （.txt 或 .md） 都可以新增至您的套件，包括非標準授權。