In the previous article, we’ve learned How to Create and Publish a NuGet Package with .NET CLI. In this article, we are going to discuss how to create and publish a NuGet package using Visual Studio. Along with that, we’ll explore a few additional options like how to provide a readme file, a license file, a package icon, etc. Additionally, we are going to require the users to accept the license agreement before installing and using our package.
So let’s get going.
Prerequisites
For this article, we are going to use:
- Visual Studio with .NET Core related workload
- The .NET CLI – Starting with Visual Studio 2017, once we choose any .NET Core-related workloads, it installs the CLI as well. Another option to get the .NET CLI is to install the .NET Core SDK
- A NuGet account– We can easily register for a NuGet account in case we do not have one already
Once we have all these in place, we can start building the app.
Preparing the Class Library
Let’s start by preparing a class library which we can package into a NuGet. We can use the same class library example that we created in the How to Create and Publish a NuGet Package with .NET CLI article. Once the project is ready, let’s proceed to configure the package properties.
For configuring the NuGet Package using Visual Studio, we can:
- Right-click on the project in the solution explorer
- Select the properties menu
- And then navigate to the Package/General menu
There, we need to provide a few details.
Package Properties
Now let’s configure the properties of the NuGet Package using Visual Studio:
Generate NuGet package on build– Once we check this checkbox, it will produce a package file every time we build the project. Let’s enable this option.
Package ID – NuGet uses this value to identify a package and hence this should be unique across the host. This is case insensitive and follows the naming rules for the .NET namespace. eg: CodeMaze.Utilities.TemperatureConverter.
Package Version – We can provide the version of our package using this option. NuGet supports the standard major.minor.patch pattern as well as the pre-release suffix. eg: 1.0.1.
Authors – Here we can provide a list of package authors separated by a comma. We should match the profile name on nuget.org so that it will cross-reference packages by the same author.
Company – We can provide the company name using this option.
Description– Here we can describe our package. It is good to give a brief explanation of what functionality this package provides.
Copyright– We can provide the copyright information here.
Tags – Using this option, we can provide a list of semi-column delimited tags. Tags help others find our package by searching and filtering. eg: Temperature, Converter.
Project URL – We can provide a URL for our package’s home page.
Icon – Using this option, we can provide an icon for our package by uploading an image file. NuGet supports JPEG or PNG file formats with a size limit of 1 MB. Also, an image resolution of 128*128 is recommended. We are going to upload an image file that complies with these rules.
There are a few additional properties, but we can skip those as they are less important. However, we are going to see how to configure a readme file and license information in the following sections.
Adding a Readme File for NuGet Package
While configuring the package properties, there is an option to upload a readme document for the package. This should be a markdown(.md) text file.
So, let’s create a readme.md file:
# TemperatureUnitConverter This package will help in converting temperature between **Fahrenheit** and **Degree Celcius** Code-Maze (c) code-maze.com
Markdown is a lightweight markup language and we can use it to create formatted text using any text editor. For learning more about markdown, we can visit Markdown Tutorial.
Once the readme file is ready, we can choose it in the readme section of the Package/General tab.
Configure the License for NuGet Package
For configuring the license, we need to provide a few details in the license section:
Package License – We need to select how we want to provide the license with the package. In our case, let’s choose Embedded File. Once we choose the Embedded File option, there will be an option to upload the license file.
License File – We can upload a license file using this option. Even though NuGet supports any text file, it is always good to follow standard license agreements as provided by MIT, Apache, etc.
Require License Acceptance – A check box that determines whether we should prompt the user to accept the license while installing this package. Let’s enable this option.
Creating the NuGet Package Using Visual Studio
For packaging a project, we can
- Right-click on the project in the Solution Explorer
- And select the Pack option
This will generate the NuGet package in the specified output folder. By default, the output folder will be bin\debug or bin\release based on the release configuration that we choose. However, there is an option to customize the output folder in the output tab of the project properties. The NuGet package will have the .nupkg extension, which is a zip file that contains the compiled assembly, all its dependencies, and other packaged files.
Also note that if we have enabled the option to generate the NuGet package on the build in the previous section, it will generate a new NuGet package every time we build the project.
Publishing the NuGet Package Using Visual Studio
Once we pack our class library into the .nupkg file, we can publish it to a host using either the .NET CLI or the nuget CLI tool. Microsoft recommends using .NET CLI over nuget CLI for publishing the NuGet packages. In this example, we are going to publish our package to the public NuGet host (nuget.org) using .NET CLI.
Before publishing to NuGet, we need to acquire an API key with sufficient privileges.
Once we acquire the API Key, we can publish our package to nuget.org by using the dotnet nuget push command:
dotnet nuget push CodeMaze.Utilities.TemperatureConverter.1.0.1.nupkg --api-key PASTE_YOUR_API_KEY_HERE --source https://api.nuget.org/v3/index.json
This will display the result of publishing action:
Pushing CodeMaze.Utilities.TemperatureConverter.1.0.1.nupkg to 'https://www.nuget.org/api/v2/package'... PUT https://www.nuget.org/api/v2/package/ Created https://www.nuget.org/api/v2/package/ 1892ms Your package was pushed.
Even after completing this step, it will take some time for our package to be indexed and appear in the search results. Meanwhile, NuGet will perform a virus scan on the package as well.
If we want to publish our package to a private feed, we just need to change the source and API Key accordingly.
While publishing NuGet packages, we may encounter errors in some scenarios. We have discussed the most common error scenarios and how to fix those in the Handling Publish Errors article section.
Managing the NuGet Package
Once we publish a package to NuGet, we can manage it from the Manage Packages part of our profile section in the portal. For instance, if we don’t wish to list the package in search results anymore, we can unlist the package from the Manage Package section in the NuGet portal.
Additionally, we can find all the information about the package including the readme file and license agreement in the portal.
Examining the NuGet Package using Visual Studio
After publishing the NuGet package, we can search for it in the NuGet Package Manager from Visual Studio.
While examining the NuGet package using visual studio, we can see all the details that we provided for the package. Notice that it displays the package icon that we uploaded. Similarly, we can see the links for viewing license and readme files. Additionally, when someone tries to install the package, they would be required to accept the license as we have enabled that option.
Conclusion
In this article, we looked at how to create and publish a NuGet package using Visual Studio. Additionally, we learned how to provide a readme file, license file, package icon and require the users to accept the license agreement before installing the package.
