开放源代码库指南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.