Setting up a releasing workflow for a .NET programming library

Building an app? Bitwarden Passwordless.dev is a developer-friendly API that allows users to sign in using passkeys with biometrics. Get started for free and see for yourself.

Developing a library involves many moving pieces, not all of which are about writing code. In a modern software development environment, developers need to think about how to build, test, and deploy the code and how those processes can be automated to be as efficient as possible.

Earlier in this blog series, it was discussed how to set up a GitHub Actions workflow to run tests for a .NET library, render the results in a human-readable way, collect code coverage metrics, and wire everything up to trigger on every commit in the repository. However, that covers only the "continuous integration" part of a would-be CI/CD pipeline.

To fully automate the library's development cycle, developers also need to take care of the delivery flow — the parts of the pipeline related to the packaging of the library, deploying it to the NuGet package registry, keeping track of released versions and associated changes, and other such tasks. Conveniently, they can leverage the groundwork laid out in this blog.

In this article, let's look at how to set up a release workflow for a .NET library. While the approaches presented here might not apply to every project, they can serve as a good starting point for developers looking to automate their library's release process.

Before diving into the details, let’s briefly go over the state of the repository being worked on, which utilizes the .NET framework. As it stands, there is a single GitHub Actions workflow that runs on every push to the repository (including pull requests) and performs the following steps:

As you can see, the workflow is pretty straightforward. It checks out the repository, installs the .NET SDK, runs the tests against the specified runtimes, collects coverage data, and uploads the corresponding reports to Codecov. To ensure the library works on all supported platforms, the above testing job is configured to run simultaneously on Windows, Linux, and macOS. Finally, to render test results in an accessible way, you can use the GitHubActionsTestLogger package, which is a custom test logger for dotnet tests that helps achieve exactly that.

To understand how to extend this workflow to include the release part of the pipeline, let’s first look at what the release process for a .NET library typically looks like. As a refresher, here’s the current repository structure:

As part of the release process, the goal is to package the library projects (Passwordless.csproj and Passwordless.AspNetCore.csproj) into their respective NuGet packages. To do that, let's use the .NET CLI, which provides a convenient dotnet pack command that can be used to create NuGet packages from a project. Similarly to the dotnet test command, there is no need to specify the project file explicitly, and one can simply run dotnet pack from the root of the repository to package all projects in the solution: 

Also, as you can see from the above output, only the library projects are packaged, and the test projects are ignored. This is because the dotnet pack command only packages projects that have the <IsPackable> property set to true. You can use this property to control which projects should be packaged and which shouldn’t without changing the arguments passed to the command.

Now, having nupkg files ready, you can upload them to NuGet to make them available for consumption. To do that, use the dotnet nuget push command, which takes a nupkg file, or a glob pattern describing such files, as an argument and uploads it to the specified NuGet feed. For example, to upload the packages to the official NuGet fee, run the following command:

Here, the **/*.nupkg glob pattern is used to match all nupkg files in the current directory and its subdirectories, and the --source argument is used to specify the NuGet feed to upload the packages to. Finally, the --api-key argument specifies the API key for authentication. This key can be obtained from your account dashboard on the NuGet website and is used to authenticate the user and authorize the upload operation.

With the above process in mind, let’s think about how to integrate them into the existing GitHub Actions workflow.

Overview of .NET platform

The .NET platform is a robust software development framework developed by Microsoft, designed to provide a comprehensive runtime environment and a rich set of libraries and tools for building and running applications across various operating systems, including Windows, macOS, and Linux. This versatile platform supports multiple programming languages, such as C#, F#, and Visual Basic, offering developers the flexibility to choose the best language for their projects.

At the core of the .NET platform are several key components. The Common Language Runtime (CLR) is the runtime environment that manages the execution of .NET code, ensuring efficient memory management, security, and exception handling. The Framework Class Library (FCL) is a vast collection of reusable libraries and classes that provide a wide range of functionality, from file I/O to web development, making it easier for developers to build feature-rich applications.

.NET Core, a cross-platform implementation of the .NET platform, allows developers to create and run .NET applications on non-Windows platforms, further enhancing the platform’s versatility. This cross-platform capability is particularly beneficial for developers looking to build applications that can run seamlessly on different operating systems.

The .NET platform offers numerous benefits, including a large and active community, a wide array of tools and libraries, and support for multiple programming languages. Its widespread use in enterprise environments makes it popular for building large-scale, high-performance applications.

To start off, let’s extend the workflow with a new job called pack. This job will be responsible for packaging the library projects into nupkg files. Packaging the library projects into nupkg files is a crucial step in the development of .NET apps, ensuring that they are ready for deployment and use. To do that, use the dotnet pack command, as discussed above:

As it stands, the above job will now execute together with the test job on each push to the repository and will create nupkg files from all packable projects in the solution. Just by performing the packaging step, you can verify that the library projects build successfully and produce valid packages; however, there is not much use if you don’t do anything with the produced files afterward.

To improve on that, you can either extend this job further by adding a step that uploads the packages to NuGet, or alternatively, delegate that responsibility to a separate job. There are benefits and downsides to both approaches, but for this example, let’s go with the latter.

In order to share the nupkg files between the pack job and our would-be deployment job, use the GitHub Actions artifacts feature. Artifacts allow us to expose specific files from a workflow to the outside world and either download them using the web interface or from inside another job.

To create an artifact, use the actions/upload-artifact action, which takes a path to a file or directory (or a glob pattern) as an argument and uploads it as a public resource. For example, to upload all nupkg files in the current directory, use the following command:

With this simple enhancement, the pack job will now produce an artifact called packages, which will contain all the nupkg files in the repository. The contents of the artifact can be inspected by downloading it from the “Artifacts” section in the workflow summary:

Now, to take care of the actual deployment process, create a new job, called deploy, which will be responsible for uploading the packages to NuGet. To do that, use the actions/download-artifact action to download the packages artifact, and then use the dotnet nuget push command to upload the packages to the NuGet registry:

As you can see, the deploy job is configured to run after both the test and pack jobs have completed successfully, which ensures that we don’t accidentally publish a broken package update. It also runs only when a new tag is pushed to the repository, which is a common way to mark new releases in git-based projects.

The command used to upload the packages to NuGet is the same as the one we discussed earlier but with the addition of the special ${{ secrets.NUGET_API_KEY }} token in place of the actual API key. This token is a GitHub Actions secret and is used to securely store sensitive information (such as API keys) in the repository. You can create a new secret by navigating to the “Settings” tab in your repository and clicking “Secrets” in the sidebar.

Looking back, keeping the deploy job separate from the pack job might seem like an unnecessary complication, especially considering that it still needs to wait for the latter to complete. However, this separation yields a few benefits:

• Smaller, more focused jobs make understanding and maintaining the workflow simpler. If you ever need to change the deployment process, we can easily do so without affecting the rest of the workflow.

• GitHub Actions allows you to re-run individual jobs if they fail instead of entire workflows. If the deploy job fails, one can re-run it without building the artifacts or running the tests again.

• You can manage the permissions of the deploy job separately from the rest of the workflow. This means that if the deploy job ends up requiring a contents: write permission – for example, to create a GitHub release – you can grant it without affecting the rest of the workflow.

• Uploading packages as artifacts can be useful even outside of sharing them between jobs. By exposing the output of the pack job, you can easily inspect the produced packages and verify their contents.

Overall, these benefits are subtle, but they can be more or less important depending on the specifics of your project.

Popular CI/CD tools for .NET

Continuous Integration and Continuous Deployment (CI/CD) tools are indispensable in modern software development. They enable developers to automate the build, test, and deployment processes, ensuring that applications are delivered quickly and reliably. For .NET development, several CI/CD tools stand out as popular choices.

Azure DevOps, a cloud-based CI/CD platform developed by Microsoft, is a top contender. It offers a comprehensive suite of features, including automated build and deployment, testing, and project management, making it a powerful tool for .NET development. Another widely used tool is Jenkins, an open-source CI/CD platform that supports a broad range of programming languages, including .NET. Jenkins is known for its flexibility and extensive plugin ecosystem, which allows developers to customize their CI/CD pipelines to suit their specific needs.

TeamCity, a commercial CI/CD tool developed by JetBrains, is another excellent option. It provides robust support for .NET development, along with a user-friendly interface and powerful build management features. AppVeyor, a cloud-based CI/CD platform, is specifically designed for .NET and other programming languages, offering seamless integration with GitHub and other version control systems.

When choosing a CI/CD tool, developers should consider factors such as ease of use, scalability, and support for their specific programming language and development environment. The right tool can significantly streamline the development process, improve code quality, and accelerate the delivery of .NET applications.

Unit testing and integration testing

Automated testing is a cornerstone of modern software development, ensuring that applications are reliable, stable, and meet the required functionality. In the context of .NET development, automated testing typically involves two main types: unit testing and integration testing.

Unit testing focuses on testing individual units of code, such as methods or classes, to verify that they function correctly in isolation. In .NET, unit testing can be performed using frameworks like NUnit or xUnit, which provide a range of features for writing and running tests. These frameworks help developers catch bugs early in the development process, reducing the risk of defects in the final product.

Integration testing, on the other hand, involves testing how different units of code interact with each other to ensure that the application functions correctly as a whole. This type of testing is crucial for identifying issues that may arise from the interaction between various components of the application.

To configure automated testing in .NET, developers can leverage tools and frameworks such as Visual Studio, which offers built-in support for both unit testing and integration testing. Additionally, third-party libraries and frameworks like Moq and Autofac can enhance testing efforts, providing mocking and dependency injection features.

By implementing automated testing, developers can ensure that their .NET applications are reliable, stable, and meet the required functionality. This reduces the risk of errors and bugs and improves the overall quality of the applications, making them more robust and maintainable.

With the above workflow in place, you can now package and deploy the library to NuGet on every new tag, but one important aspect of the release process hasn’t been covered yet: versioning. In a typical .NET library, the version number is a crucial piece of information that helps consumers understand the significance of a particular release and decide whether to upgrade to it.

Versioning is critical to .NET programming, helping developers manage and track changes across different releases.

The most common approach to versioning is just to set the value of the <Version> project property whenever a new release is made. Although it requires manual intervention, it’s straightforward, gives you complete freedom over the versioning scheme, and keeps the repository free of additional tooling or configuration.

Then, the typical release process would consist of the following steps:

• Update the version number in the project file

• Commit the change

• Push the commit

• Create a new tag (1.2.3)

• Push the tag

• Workflow runs and deploys the new version to NuGet

This approach works well for most projects, but it can be error-prone. The biggest issue is that the version number needs to be updated in two places: the project file and the tag. It’s easy to forget to update them both or to make a mistake. Additionally, if you plan to make releases often, the above versioning process can become somewhat tedious.

An alternative approach is to use the git tag as the only source of truth for the version number. This way, the version number is always in sync with the tag, and the release process becomes as simple as creating a new tag without updating any code.

In such a setup, the version number in the project file is usually set to a placeholder value, such as 0.0.0-local, and is never updated. Instead, the actual version number is derived from the tag name and is passed as a parameter during the build. Here’s how to do that in a GitHub Actions workflow:

In the above example, use the ${{ github.ref_name }} token to pass the tag name as the value of the Version property to the dotnet pack command. This way, the version number of the deployed packages will always match their tag name, and you don’t need to update the project file manually.

With this setup, the release process is shortened to just the following few steps:

• Create a new tag (1.2.3)

• Push the tag

• Workflow runs and deploys the new version to NuGet

Pre-releases are another thing you may want to account for in your versioning strategy. Pre-releases are versions that are not considered stable and are typically used to distribute early versions of a library to a limited audience for testing. NuGet natively supports semantic versioning, so pre-releases are denoted by appending a hyphen (-) and an alphanumeric identifier to the version number, such as 1.2.3-alpha.

The existing setup works just as well for manually created pre-releases. You can simply push a tag with a pre-release version, and the workflow will deploy the corresponding package to NuGet.

However, you may also want to create and deploy pre-release packages automatically, for example, on every commit. Because there is no tag from which to derive the version number, you’ll need to come up with a different way to generate pre-release package versions. There are a few common approaches to solve this:

1. Approach 1: Use a placeholder version, such as 0.0.0, and just append the commit hash to it: 0.0.0-ci-7ca0ec0. This is the simplest approach, but it might make it harder for the consumer to understand the significance of a particular pre-release or where it belongs in regard to existing, stable releases. Effectively, you’ll end up having two separate versioning threads, which can be confusing.

2. Approach 2: Automatically generate a version by bumping the patch number of the latest stable release (git tag) and appending the commit hash to it: 1.2.4-ci-7ca0ec0. This approach is more consistent with the versioning scheme you’d already be using for stable releases, but it requires a bit more work to implement. A bigger downside, however, is that the versioning scheme is not semantic – your pre-release may involve breaking changes, but since only the patch number is ever bumped, the version would not reflect that.

3. Approach 3: Pull the latest stable package from NuGet and compare it to the package produced by the current workflow. Then, depending on the changes introduced in the public API, automatically evaluate whether to bump the major, minor, or patch number of the version. While this approach is the most accurate, it’s also the most complex to implement, and it requires a lot of additional tooling and configuration.

Ultimately, because of the complexity involved, it was decided to go with the first option for the Passwordless .NET SDK, as it’s very simple to implement and understand, and it’s good enough for our needs. Here’s how you can update the workflow form earlier to support automatic pre-releases with this approach:

Note that while you can publish packages frequently to NuGet.org, it’s generally discouraged to deploy a new pre-release on each commit, as shown above. Instead, it’s recommended that you use a private feed, such as GitHub Packages or MyGet, to do that. For example, here’s how you can modify the deploy job to publish pre-releases to GitHub Packages:

Another important aspect of the release process is keeping track of the changes introduced in each version of the library. This is typically done using a changelog, which is a file that contains a list of all changes made to the library, organized by version. The .NET Foundation plays a significant role in fostering open development and collaboration, which is essential for maintaining a comprehensive changelog.

There are a few different strategies for maintaining a changelog. Most library projects opt for a manually maintained changelog file (typically CHANGELOG.md in the repository root), which is updated by the maintainers whenever a new release is made. The changelog can follow a well-established format, such as Keep a Changelog, which provides a set of conventions for how to structure the file and makes it easier for certain tools to parse them, such as Dependabot.

However, maintaining a changelog manually can be a bit tedious. Luckily, GitHub can make things a bit simpler with the help of the automatically generated release notes. This feature allows you to automatically generate a changelog based on the pull requests merged since the last release and include it inside the description when you make a new release. It does require that all meaningful changes are applied via pull requests, even if working alone, and that you make a GitHub release for each new version, but the automation benefits are well worth it.

With the workflow that is now in place, there are no changes necessary in order to get the changelog generation working. All you have to do is draft a new release on GitHub, assign it to a tag you pushed earlier, and click “Generate release notes”.

You can also choose to let GitHub create the tag for you as you publish the release, which will trigger the deploy job just as if you had pushed the tag manually. With this approach, your release process will look like this:

• Publish a new release on GitHub with auto-generated release notes

• Workflow runs and deploys the new version to NuGet

If you prefer to avoid the manual step of creating a new release through the GitHub web interface, you can also automate that part of the process. To create a new release programmatically, you can use the GitHub API or, more conveniently, the GitHub CLI. When doing either, you have the option to include auto-generated release notes in the description of the release. For example, below is how you can achieve that with the GitHub CLI: BashCopy $ gh release create 1.2.3 --repo my/repo --generate-notes

The gh tool is already pre-installed on GitHub-hosted runners, so to incorporate this into our workflow, we only need to update our deploy job with one extra step.

Here, the step we added is responsible for creating a new release on GitHub and uploading the packages as assets. The --generate-notes flag tells the gh tool to automatically generate release notes based on the pull requests merged since the last release and include them in the description of the release. The --verify-tag flag tells the tool to verify that the tag exists before creating the release as a sanity check to ensure that the release is being created for a valid tag.

Finally, with this setup, the release process is optimized to the following few steps:

• Push a new tag (1.2.3)

• Workflow runs, creates a release, and deploys the new version to NuGet

This article covered how to set up a release workflow for a .NET library based on what was learned from the Bitwarden team's experience building the Passwordless .NET SDK. The existing GitHub Actions workflow has been extended to include a new job that packages the library projects into nupkg files and another job that uploads the packages to NuGet. Additionally, a few other topics are covered, such as how to handle versioning and pre-releases and how to automate the generation of release notes.

Are you a developer looking to add passkey authentication using biometrics to your applications? Quickly get started with a free Passwordless.dev account, or visit Passwordless.dev to learn more about the offering.

Still have questions? Check out our community pages and share your thoughts and questions there.