Introduction
When I began learning about C# and the .NET framework, I ended up using some different external packages to bring in some extra functionality. For one specific project, I required use of the DocumentFormat.OpenXml package to create some word-processing elements. As I searched how to get the package (I was and still am a new software developer), I found out that I needed to use the NuGet Package Manager to install the OpenXml package. I realized that I did not know much about working with external libraries (i.e. through NuGet), so this post is about a superficial understanding of NuGet, including what it is, how to use it, why it is useful, when to use it, some examples of its use, and some additional helpful resources for further learning.
What is NuGet?
NuGet is a package manager for the .NET framework (ecosystem).
NuGet is the "Microsoft-supported mechanism" for sharing .NET code. A NuGet package is a ZIP file with the .nupkg or .nupack extension that contains compiled code, related files, and information on the package.
The packages are created by users who develop reusable code that they share with a host. Users of the third party code obtain it from the host and NuGet serves a an intermediate to transfer the code from host to user.
A package is a "compiled library packed together with descriptive metadata into a sharable unit".
The NuGet client app (nuget.exe) is also free and open source, so you have the ability to help improve this application.
When is NuGet useful?
NuGet is useful for anyone wanting to bring additional functionality from custom libraries into a project, specifically for projects using the .NET framework. NuGet is supported by the following in its latest version (recommended latest is 6.3.0 at the time of this post): C#, Visual Basic, F#, WiX, and C++.
NuGet is also useful for those who want to create their own custom functionality that other .NET users can utilize (see below for how to create and publish a NuGet package).
Why learn about NuGet
Learning about external libraries and custom functionality will allow you to avoid the hassle of creating the functionality yourself, saving memory and time. People create NuGet packages to help others' code by making what they create reusable. This will also make you a more versatile programmer and coder since being familiar with external functionality shows that you understand and can apply others' code.
How to find and evaluate NuGet packages for your project
Below, I have laid out an example of using a NuGet package for a project; however, see this link for a more detailed visualization and description of how to find and use NuGet packages for your projects:
Microsoft docs: how to find and evaluate NuGet packages for your project
Example of NuGet in use
An example of a NuGet package I have used with a project is the DocumentFormat.OpenXml package. I used this to help format word-processing functionality and generate Microsoft Word documents in C#.
Here are some steps to download the DocumentFormat.OpenXml NuGet package in Visual Studio:
1) Either by using the Tools tab or right clicking on your solution, go to Manage NuGet packages.
2) Under the Browse tab, search for DocumentFormat.OpenXml, check it, and click "Add Package".
3) Now you should be able to use the DocumentFormat.OpenXml NuGet package! Now all you have to do is type "using" at the top of your project to specify the namespace (in this case the namespace is the package). For this project, I used DocumentFormat.OpenXml.Wordprocessing to allow myself to create a Paragraph object.
Installation and use of the NuGet CLI
Since Visual Studio Code does not have an integrated NuGet package manager that can install packages, this section explains how you can get around that with the CLI, which is also useful to know without Visual Studio Code. This way, your use and acquisition of NuGet packages can be done in more ways than just the Visual Studio NuGet Package Manager
Here are the steps to install and use the NuGet Command Line Interface, nuget.exe (Microsoft NuGet CLI Reference):
Windows:
1) Visit https://nuget.org/downloads and select version 3.3 or higher to be compatible with Mono.
2) Save the nuget.exe file to a folder of your choice.
3) Add the folder with the nuget.exe file to your PATH environment variable
macOS/Linux:
1) Install Mono version 4.4.2 or higher
2) Execute the following command:
# Download the latest stable `nuget.exe` to `/usr/local/bin`
sudo curl -o /usr/local/bin/nuget.exe https://dist.nuget.org/win-x86-commandline/latest/nuget.exe
3) Create an alias, using the following script and add it to an appropriate file.
# Create as alias for nuget
alias nuget="mono /usr/local/bin/nuget.exe"
4) Reload the shell and test the installation by entering the nuget keyword
See the reference link (NuGet CLI Reference) for more details on availability, commands, and applicability of the NuGet CLI.
How to create and publish a custom NuGet package
Here is a short recap of a tutorial video on creating and publishing your own NuGet package via the .NET CLI in VS Code:
Create a new class library via the CLI:
$ dotnet new classlib
Insert the code that you want to use for your library into the Class1.cs file (or whatever you renamed this file). The video writes simple functionality to log text to the console, and that's it. Your code is not required to be complex to be published.
-
Modify the package metadata in the AppLogger.csproj file (or whatever you renamed it). Here are some considerations and tips for this step:
a. Create a uniquely-named PackageId element within the parent TargetFramework element (company.product.feature is a popular convention for this). Put the name between the PackageId element tags.
b. Create an author element that specifies whomever is responsible for publishing this library (i.e. yourself, your company, etc.)
c. Include a description element.
d. Include a PackageLicenseExpression so others are able to use the library in their project(s) without restrictions.
e. Create package tags to allow the user to search for your library with keywords.
f. Include a repository URL if you have your source code saved in one.
Save the project and generate the NuGet package in the CLI using the following syntax:
$ dotnet pack
Publish the NuGet package. One way to do this is by copying the path (ending in .nupkg) generated to the right of "Successfully created package" in the terminal, go to nuget.org, sign in, go to Upload, hit Browse, paste the path into the File name input, hit Open, verify your metadata in the found package, then hit Submit. Before it can be found on nuget.org, validation and indexing must be done, so the published library will take some time to be found on nuget.org.
Use the link below to follow the descriptive video that came up with these steps.
Microsoft docs: how to create and publish a NuGet package with the .NET CLI
Since your NuGet package has now been successfully uploaded to nuget.org, you can not see where to find what custom NuGet packages contain, their stability, and whether they would be useful for your project. The listing page should contain all of this information. Also, see the package's Info page to navigate to its website to acquire even more useful information.
Conclusion
To drive home the main points from above:
1) NuGet is the preferred .NET package manager for installing external functionality into projects.
2) Any .NET language can use NuGet (C#, F#, Visual Basic, Wix, and C++ all support NuGet's latest version).
3) You can install and use a NuGet package in Visual Studio by navigating to your Tools tab or right clicking your solution (shown above).
4) Creating a NuGet package is relatively simple and can be done in a few steps (shown above).
5) This post heavily referenced the Microsoft docs, so if you would like to learn more, I would highly recommend checking them out. A lot of the links referenced below will lead you to plenty of other documentation.
A few other bits of NuGet information/use
1) NuGet can build create packages in Mono, and nuget.exe "builds and runs under Mono 3.2+" (Microsoft NuGet FAQ's)
2) To check on the version of the NuGet Tools you have in Visual Studio, go to Help > About Microsoft Visual Studio and see the version next to NuGet Package Manager. Also, you can use the Package Manager Console (Tools > NuGet Package Manager > NuGet Package Manager Console) and enter host to see th details of your version of NuGet.
3) You can add your own commands to nuget.exe
References and resources to learn more about NuGet
NuGet documentation: Microsoft docs
What is NuGet and what does it do? Microsoft docs
Microsoft docs: how to create and publish a NuGet package with the .NET CLI
Microsoft docs: how to find and evaluate NuGet packages for your project
Top comments (3)
Very useful I just want to add that you can also add nuget packages using the command
dotnet add package Microsoft.EntityFrameworkCoreincluded in dotnet CLIinfo:
learn.microsoft.com/en-us/dotnet/c...
Awesome! Thanks for the addition!
Nice.