.NET Library Starter Kit

A battle-tested starter kit for building open-source and internal NuGet libraries, born from half a billion downloads.

About • Download • How To Use • Building • Contributors • Versioning • Credits • Related • License

About

What's this?

A bunch of dotnet new templates to quickly get you started building high-quality binary or source-only open-source and non-open-source libraries including everything you need to publish it on NuGet or make it available as open-source.

It includes:

• Multi-targeting to cover as many .NET frameworks as possible
• Separate templates for internal (or "inner sourced") as well as open-source libraries
• Support for both GitHub and Azure DevOps Repositories/Pipelines
• Can create projects for binary or source-only packages
• Code coverage using Coverlet and Coveralls.io
• Static code analysis using Roslyn analyzers StyleCopAnalyzers, Roslynator, CSharpGuidelinesAnalyzer and Meziantou.
• Auto-formatting using (a slightly opinionated) .editorconfig and settings honored by JetBrains Rider and ReSharper
• A Nuke C# build script that you can run locally as well as in your CI/CD pipeline
• A GitHub Actions workflow that builds, tests, packages and publishes your library
• GitHub issue templates to streamline bug reporting and feature requests
• An extensive read-me
• Automatic versioning using GitVersion and tagging
• Contribution guidelines
• Customized release notes templates for GitHub connected to pull requests labels.
• A test project using xUnit and Fluent Assertions 7
• Validation of the public API of the library against snapshots using Verify
• NuGet auditing using .NET built-in auditing capabilities
• NuGet package and licensing scanning through PackageGuard

What's so special about that?

I like to build my software systems in a nicely broken down set of libraries that are easy to maintain, test and deploy based on the Principles Of Successful Package Management. However, every time I or the teams I work with need to start a new library or reusable component, we have to piece together so much from other projects that I felt this would fill the gap.

This is the result of years of experience in building in-house and open-source libraries that are used by thousands of developers around the world. I hope it's a great starting point for building your own libraries.

Tip You can also use this as a starting point for a GitHub Template Repository, fork and adapt the repository for your own company, or use it as an organization template in Azure DevOps.

Who created this?

My name is Dennis Doomen and I'm a Microsoft MVP and Principal Consultant at Aviva Solutions with 29 years of experience under my belt. As a coding architect, I specialize in designing full-stack enterprise solutions based on .NET as well as providing coaching on all aspects of designing, building, deploying and maintaining software systems. I'm the author of several open-source projects such as Fluent Assertions, Reflectify, Liquid Projections, and I've been maintaining coding guidelines for C# since 2001.

Contact me through Email, Bluesky, Twitter/X or Mastadon

Download

This repository is available as a NuGet package on https://nuget.org. To install it, use the following command-line:

dotnet new install DotNetLibraryPackageTemplates

You can update the templates using the following command.

dotnet new update

How do I use it?

Generating the library skeleton

1. Create a new directory for your library initialized with Git

2. Run the following command to start building an internal library for GitHub

   dotnet new nooss-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary

   Or, if you prefer to build a NuGet package that only adds source files to a project (and avoids binary dependencies)

   dotnet new nooss-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary

   Or, if you want to build an open-source packages, use either of the following

   dotnet new oss-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary

   dotnet new oss-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary

   If you are still using Azure DevOps, we got you covered, but you need the organization and project names as well. Again, choose between a binary package or a source-only package.

   dotnet new azdo-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary --organization MyDevOpsOrganization --project MyDevOpsProject

   dotnet new azdo-source-only-nuget-class-library-sln --name TheNameOfYourAwesomeLibrary --organization MyDevOpsOrganization --project MyDevOpsProject

3. Make the necessary changes to the generated code (see next section)

4. Commit the changes to your repository into a new commit. Without it, the build script will crash on generating the version number.

5. Run build.ps1 to build the code, run the tests, and package the library into a NuGet package in the Artifacts directory.

What to do after that

The generated solution contains a read-me that provides additional tips to get started.

Additional things to be aware of

About NuGet auditing

By default, a dotnet restore will also check the NuGet packages for any vulnerabilities. If you run into those, there are a couple of options you can take.

1. Update the dependencies to a version that resolve the vulnerability
2. Update the WarningsNotAsErrors element in the Directory.Build.Props file to include the relevant NU190x error codes as listed here.
3. Disable auditing entirely by setting the NuGetAudit element to false in that same Directory.Build.Props file.

About API verification

The ApiVerificationTests will generate a .txt file containing a representation (per target framework) of the public API of your library. It's a nice technique to prevent accidentally introducing breaking changes. So, whenever the structure of your API changes compared to the snapshot stored in the ApprovedApi folder, the test will fail. You can then use AcceptApiChanges.ps1 to update the snapshots and make the test succeed again. Alternatively, you can install the plug-in Verify Support by Matthias Koch to do this from inside JetBrains Rider or ReSharper.

Building

To build this repository locally, you need the following:

• The .NET SDKs for .NET 4.7, 6.0 and 8.0.
• Visual Studio, JetBrains Rider or Visual Studio Code with the C# DevKit

You can also build, run the unit tests and package the code using the following command-line:

build.ps1

Or, if you have, the Nuke tool installed:

nuke

Also try using --help to see all the available options or --plan to see what the scripts does.

Contributors

Your contributions are always welcome! Please have a look at the contribution guidelines first.

(Made with contrib.rocks)

Versioning

This library uses Semantic Versioning to give meaning to the version numbers. For the versions available, see the tags on this repository.

Credits

This library wouldn't have been possible without the following tools, packages and companies:

• ASP.NET Core Template - Created by Nikolay Kostov and the inspiration for this repo.
• Scriban - A fast, powerful, safe and lightweight scripting language and engine by Alexandre Mutel
• Nuke - Smart automation for DevOps teams and CI/CD pipelines by Matthias Koch
• Rider - The world's most loved .NET and game dev IDE by JetBrains
• xUnit - Community-focused unit testing tool for .NET by Brad Wilson
• Coverlet - Cross platform code coverage for .NET by Toni Solarin-Sodara
• Polysharp - Generated, source-only polyfills for C# language features by Sergio Pedri
• GitVersion - From git log to SemVer in no time
• ReportGenerator - Converts coverage reports by Daniel Palme
• StyleCopyAnalyzer - StyleCop rules for .NET
• Roslynator - A set of code analysis tools for C# by Josef Pihrt
• CSharpCodingGuidelines - Roslyn analyzers by Bart Koelman to go with the C# Coding Guidelines
• Meziantou - Another set of awesome Roslyn analyzers by Gérald Barré
• Verify - Snapshot testing by Simon Cropp

Support the project

• Github Sponsors
• Tip Me
• Buy me a Coffee
• Sponsor Me

You may also like

• My Blog
• FluentAssertions - Extension methods to fluently assert the outcome of .NET tests
• PackageGuard - Get a grip on your open-source packages
• Reflectify - Reflection extensions without causing dependency pains
• Pathy - Fluently building and using file and directory paths without binary dependencies
• C# Coding Guidelines - Forkable coding guidelines for all C# versions

License

This project is licensed under the MIT License - see the LICENSE file for details.