開放原始碼程式庫指導Open-source library guidance

這份指導提供協助開發人員建立高品質 .NET 程式庫的最佳做法建議。This guidance provides recommendations for developers to create high-quality .NET libraries. 本文件的重點在於建置 .NET 程式庫時的「內容」與「原因」,而不是「方法」。This documentation focuses on the what and the why when building a .NET library, not the how.

高品質開放原始碼 .NET 程式庫的各個層面:Aspects of high-quality open-source .NET libraries:

  • 包山包海 - 致力於支援多種平台、程式設計語言與應用程式的優質 .NET 程式庫。Inclusive - Good .NET libraries strive to support many platforms, programming languages, and applications.
  • 穩定可靠 - 優質的 .NET 程式庫可在 .NET 生態環境中共存,能在使用多種程式庫建置而成的應用程式中執行。Stable - Good .NET libraries coexist in the .NET ecosystem, running in applications built with many libraries.
  • 具備演進能力 - .NET 程式庫應該要隨著時間改善與演進,同時支援現有的使用者。Designed to evolve - .NET libraries should improve and evolve over time, while supporting existing users.
  • 可供偵錯 - .NET 程式庫應使用最新工具來為使用者打造良好的偵錯體驗。Debuggable - .NET libraries should use the latest tools to create a great debugging experience for users.
  • 值得信賴 - .NET 程式庫使用安全性最佳做法來發行到 NuGet,以獲得開發人員的信任。Trusted - .NET libraries have developers' trust by publishing to NuGet using security best practices.

建議類型Types of recommendations

每篇文章都呈現四種類型的建議:優先考慮避免禁止Each article presents four types of recommendations: Do, Consider, Avoid, and Do not. 建議類型指出應遵循的程度。The type of recommendation indicates how strongly it should be followed.

您應該一律遵循優先類型的建議。You should almost always follow a Do recommendation. 例如,For example:

✔️使用 NuGet 套件來散發您的程式庫。✔️ DO distribute your library using a NuGet package.

至於考慮建議則通常應該遵循,但也會有不符合規則的例外,而您不必因為沒有遵循指導而感到自責:On the other hand, Consider recommendations should generally be followed, but there are legitimate exceptions to the rule and you shouldn't feel bad about not following the guidance:

✔️考慮使用SemVer 2.0.0來為您的 NuGet 套件版本。✔️ CONSIDER using SemVer 2.0.0 to version your NuGet package.

避免建議指的是通常不建議採行的建議,但有時違反規則尚屬合理情況:Avoid recommendations mention things that are generally not a good idea, but breaking the rule sometimes makes sense:

❌ 避免需要確切版本的 NuGet 套件參考。❌ AVOID NuGet package references that demand an exact version.

最後,禁止類型的建議表示在多數情況下都不應採取的動作:And finally, Do not recommendations indicate something you should almost never do:

❌ 不要發佈程式庫的強式名稱和非強式名稱版本。❌ DO NOT publish strong-named and non-strong-named versions of your library. 例如 Contoso.ApiContoso.Api.StrongNamedFor example, Contoso.Api and Contoso.Api.StrongNamed.