New prescriptive guidance for Open Source .NET Library Authors
There'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.
About Newsletter
I know we should not use strong naming for security anymore - so what about Authenticode signing?
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.
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.
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