Practical .NET

The Easiest Way to Share Code: NuGet

You want to use a DLL in multiple projects (it's even possible that other developers at your company might find your DLL helpful). The easiest way to distribute and deploy that DLL, or any other combination of files, is with NuGet. Really.

• By Peter Vogel
• 11/23/2015

In an earlier column driven by reader input, I built an ASP.NET MVC HtmlHelper that simplified creating the standard combination of label, textbox and validation message. That helper also supported a client-side "Dirty" flag that would be set when there was a change on the page. (The solution even handled those situations when a user makes a change in a page and then backs the change out.)

There was one problem with my solution: It required a combination of compiled Microsoft .NET Framework and JavaScript code. As a result, if someone else wanted to use my HtmlHelper, integrating it into their application would be a pain.

But this is where NuGet comes in: It makes it easy to integrate any combination of DLLs, JavaScript files or any other thing you can think of, into a project. Even if all you want to share is a customized set of Entity Framework classes in a single DLL, it's easier for the developer to add that DLL to his project through NuGet than to go hunting for that DLL on some file share. In addition, NuGet allows you to provide searchable, descriptive text with your package so that the developer using the NuGet Package Manager from Visual Studio can know what he's about to add to his project. NuGet even simplifies life for the developer when he wants to upgrade to a newer version of your package: He just picks the Update tab in the NuGet Package Manager to find which packages in his project have newer versions.

There are two parts to using NuGet, though: Creating a NuGet package from an existing project's components and then making that package available to Visual Studio. I'll start with creating a NuGet package, using my HtmlHelper as an example, and then show the easiest way to make your package available to the Visual Studio NuGet Package Manager.

Documenting a NuGet Package
While you can create a NuGet package from the command line, typing obscure commands isn't my first choice -- I prefer to use a GUI. If that's your preference also then your first step is to download the NuGet Package Explorer. Once the Package Explorer is downloaded, it will open automatically (you'll also find it in your Start menu under NuGet Package Manager when you want to use it again).

NuGetPackage Manager Explorer splits its screen in two: on the left is a pane displaying the package's documentation (labeled "Package metadata") and on the right is a pane listing the files in your package (labeled "Package contents"). To start creating a new package, pick New from the File menu. After that, you can use either pane, but I'd suggest you start on the left with the Package metadata by entering the documentation the developer will see when he picks your package from the NuGet Package Manager. My reasoning is that, if you start with the documentation, you'll have a chance to revise it after you've added your files to your package and have a better understanding of what your package consists of.

To create your package's documentation, click on the document icon in the top left corner of the Package metadata pane. While there's lots of information you can enter, the four critical items are:

• Id (which must be unique)
• Authors (a comma-delimited list of the package's authors)
• Title
• Description

The Title and Description are what developers will see in the NuGet Package Manager, so you want to provide all the information developers might need to find your package, recognize it and know what it does. Optionally, you can also enter into the Tags textbox any keywords that developers might use when looking for your package that don't appear in your Title or Description. To save your changes, click the green checkmark in the upper-left corner of the Package metadata pane.

Creating a NuGet Package
When a developer adds your package to his project, he'll want the components of your package to go into the right folders in his project. Therefore, your first task in adding files to your package is to add those folders to your package. For example, I want my JavaScript file to go into the project's Scripts folder in a subfolder called PHVIS. To add that folder structure to my package, I first need to add a content entry to the Package contents pane: From the Package Explorer Content menu, I select Add | New Folder, and from the submenu, I select Content. The content entry appears in the Package contents pane.

With that entry in place, I'm ready to add the folder structure for my JavaScript file. In the Package contents pane, I right-click on the content entry, select Add | New Folder, and in the resulting dialog give the folder the name Scripts before clicking the OK button. After the Scripts folder appears under the contents entry, I right-click on it and select Add New Folder to add my PHVIS folder. Finally, I right-click on PHVIS folder, select Add Existing File, surf to my project, find my JavaScript file and double-click on it to add it to my package's contents. Now, when a developer adds my package to his project, he'll find that JavaScript file in his project's Scripts/PHVIS folder.

If you prefer, you can also drag files from Windows Explorer into the Package contents pane. If you do, Package Explorer will take its best guess at what entry the file should go into. If, for example, I drag the DLL for my HtmlHelper out of Windows Explorer and drop it on the Package Contents pane, Package Explorer pops up a dialog asking if I want to add the DLL to the lib folder. Because I do, I just accept the offered choice: My DLL appears in the Package contents pane, nested inside the lib entry. I could've done the same with my JavaScript file if I hadn't wanted to control the folder and subfolder in which the file appeared.

If you find that your folders aren't nested correctly in the Package contents pane, you can drag them to where you want them. If you want to check that you've got all of your packages in all the right folders, from the Package Explorer File menu, select Export and pick a folder in the resulting Choose a folder dialog. Package Explorer will unpack your package into that folder for you to review.

Adding a NuGet Source
Now it's time to save your package somewhere that you (and other developers) can find it. The easiest solution is to tell Visual Studio to use a folder on a network share when looking for NuGet packages. This is the one part of the process where'll you need the cooperation of the other developer because he'll need to tell his Visual Studio about your new folder. You'll also need to save your package to that folder using the Save option on the Package Manager File menu, of course.

To get your copy of Visual Studio to search for NuGet packages in your new folder, from the Tools menu, select Options. Then, from the left-hand list in the resulting dialog, expand the NuGet Package Manager choice to display the Package Sources entry. Select that entry and you'll see your current list of package sources on the right side of the Options dialog (you can also get to this dialog from the Manage NuGet Packages dialog box -- just click the Settings button in the lower-left corner that you've been ignoring).

To add your NuGet package folder to Visual Studio, click the plus sign button in the upper-right hand corner of the dialog. This adds a new source item to the list already filled in with some default values. To update those default entries, make sure your new source is selected and enter your values in the textboxes at the bottom of the dialog. You need to give your source a name (for example, PHVIS Package Source) and a source, which is the full path to your NuGet package folder (for example, C:\NuGet).

Now, in the Visual Studio Manage NuGet Packages dialog, you'll find your new Package Source listed under the Online tab. Picking your source will list all the packages in the folder. If you select the All option, you'll even find your package mixed into the resulting list with the packages from the regular NuGet sources. When you select your package and click Install, your package will be added to the current project.

Personally, I find that pretty cool -- makes me feel like I'm playing with the big boys. If you'd prefer to keep your NuGet packages in a Web site (like Microsoft does), you can do that, too. Fortunately, that's so simple I can cover it in a tip later this month.