Scott Hanselman

New prescriptive guidance for Open Source .NET Library Authors

October 16, 2018 Comment on this post [5] Posted in DotNetCore | Open Source
Sponsored By

Open-source library guidanceThere's a great new bunch of guidance just published representing Best Practices for creating .NET Libraries. Best of all, it was shepherded by JSON.NET's James Newton-King. Who better to help explain the best way to build and publish a .NET library than the author of the world's most popular open source .NET library?

Perhaps you've got an open source (OSS) .NET Library on your GitHub, GitLab, or Bitbucket. Go check out the open-source library guidance.

These are the identified aspects of high-quality open-source .NET libraries:

  • Inclusive - Good .NET libraries strive to support many platforms and applications.
  • Stable - Good .NET libraries coexist in the .NET ecosystem, running in applications built with many libraries.
  • Designed to evolve - .NET libraries should improve and evolve over time, while supporting existing users.
  • Debuggable - .NET libraries should use the latest tools to create a great debugging experience for users.
  • Trusted - .NET libraries have developers' trust by publishing to NuGet using security best practices.

The guidance is deep but also preliminary. As with all Microsoft Documentation these days it's open source in Markdown and on GitHub. If you've got suggestions or thoughts, share them! Be sure to sound off in the Feedback Section at the bottom of the guidance. James and the Team will be actively incorporating your thoughts.

Cross-platform targeting

Since the whole point of .NET Core and the .NET Standard is reuse, this section covers how and why to make reusable code but also how to access platform-specific APIs when needed with multi-targeting.

Strong naming

Strong naming seemed like a good idea but you should know WHY and WHEN to strong name. It all depends on your use case! Are you publishing internally or publically? What are your dependencies and who depends on you?

NuGet

When publishing on the NuGet public repository (or your own private/internal one) what do you need to know about SemVer 2.0.0? What about pre-release packages? Should you embed PDBs for easier debugging? Consider things like Dependencies, SourceLink, how and where to Publish and how Versioning applies to you and when (or if) you cause Breaking changes.

Also be sure to check out Immo's video on "Building Great Libraries with .NET Standard" on YouTube!


Sponsor: Check out the latest JetBrains Rider with built-in spell checking, enhanced debugger, Docker support, full C# 7.3 support, publishing to IIS and more advanced Unity support.

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Hosting By
Hosted in an Azure App Service
October 16, 2018 8:27
As a long-term author of various open-source projects (FluentAssertions, FluidCaching, LiquidProjections) and C# Coding Guidelines, I would go even further with this.

In my opinion, a great library:
- Has a clear release strategy
- Controls its dependencies
- Is unopinionated (though that can be difficult)
- Uses DRY within boundaries
- Has clear documentation (readme, sdk, contribution guidelines, etc)
- Has intention-revealing unit tests
- Uses semantic versioning
- Doesn't use static mutable state
- Has (semantic) release notes

Also check out my slide deck on this at https://www.slideshare.net/dennisdoomen/build-libraries-that-people-love-to-use
October 16, 2018 10:41
What about signing? Shouldn't trustworthy libraries be signed as well so we can be sure that the original library author published an update?

I know we should not use strong naming for security anymore - so what about Authenticode signing?
October 16, 2018 13:51
@Dennis

These initial articles focus on cross-platform and packaging. Recommendations for library design is something we'll consider adding in the future.

@D.R.

In the modern .NET eco-system NuGet provides a form of identity. That is mentioned on the page about publishing to NuGet and trust. Expanding that out into an article discussing trust, security and signing is something I'd like to see.
October 16, 2018 19:16
In my opinion, a great library is:
* Simple
October 17, 2018 20:35
Correct me if I am wrong, but I do not believe JSON.NET (Newtonsoft.Json) includes the snk (strong name key) in the public GitHub repository.

I also believe projects like Dapper include strong naming as a separate package (Dapper.StrongName) as well.

Are these library maintainers considering this new prescription or who is this intended for?

Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.