I absolutely love NuGet. Having a package management system in place makes it so much easier not only to use shared code, but it also makes it easier to share. For instance, say you had a class or assembly that you think other people might find useful. The old way to do it was to pick one of the many project-hosting sites, build a deployable assembly, upload the assembly, and hope people found it. And even if someone did find it, you were either limited in how you could integrate with their project or you had to include long, drawn out integration instructions. But no longer!
With NuGet, you have the ability to control your shared code’s integration with a project. You can add files to the directory tree, transform the web.config, or even run a PowerShell script. The PowerShell script can even be used to add commands to the Package Console, so your shared code can include tooling along with it. But for your first foray into the world of NuGet, you’ll probably want to start as simply as possible. So that’s the scenario I’ll cover here—packaging a single file.
If you’re following along and would like an example, the current source for my actual first NuGet package is on GitHub: https://github.com/davecowart/AutoMapperPagedList
Step 1: Write Your Code
You’re on your own here.
Step 2: Build Your Package Folder Structure
Create a folder for your package. Inside that folder, create another folder named ‘content’. Anything that goes inside content will be placed in the root of the project folder, so inside that content folder you can simulate the folder structure for any files you want to include in the project. In this instance, I have a single class I’d like to include in the Models folder, so I created the folder structure [package root]/content/Models and placed my file there.
Step 3: Build Your NuSpec File
The glue that holds it all together is the NuSpec file. This XML file contains all the package information that NuGet needs in order to identify, share and deploy your package. For this step, you’ll need to install nuget.exe. If you have NuGet installed, you probably already have it. Run
nuget in the command line to see if you have it, and if you do run
nuget update to make sure you have the latest version.
Once you have the NuGet executable straightened up, navigate to your package’s root folder in the command line. Run
nuget [projectname] to create the
.nuspec file, and open it up in a text editor. For this package, only a minimal amount of information is needed:
<?xml version="1.0"?> <package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"> <metadata> <id>AutoMapperPagedList</id> <version>0.6</version> <authors>Dave Cowart</authors> <owners>Dave Cowart</owners> <requireLicenseAcceptance>false</requireLicenseAcceptance> <description>Adds an implementation of PagedList that uses AutoMapper to emit ViewModels</description> <tags>PagedList, AutoMapper, ASP.NET</tags> <dependencies> <dependency id="AutoMapper" version="1.0" /> </dependencies> </metadata> </package>
In this case, the package has a dependency on another package—AutoMapper. The id used in the dependency element is the same as the name used in AutoMapper’s NuSpec file. That id is used as the name pretty much throughout NuGet, so it’s easy to find if you need it. Just make sure that your chosen id is unique, descriptive, and free of any crazy special characters.
Step 4: Package It Up
Head back to the command line and run the command
nuget pack [packagename].nuspec. This will create the
.nupkg file you’ll need to upload to NuGet.
Step 5: Upload to NuGet
Before you actually upload to the NuGet library, you’ll need to register and get your API key. Register for an account at http://nuget.organd go to My Account. Copy the access key and head back to the command line once again. Run
nuget setApiKey [apikey] to set your API key (you’ll only need to do this one time, even if you’re creating multiple packages).
Once your API key is set, run
nuget push [packagename].nupkg. This will upload your package to the library, and it’ll be available in just a couple minutes. To check on it, go back to http://nuget.org and go to Contribute > Manage My Packages. From this page, you’ll get a list of all the packages you’ve shared, along with the total number of reviews and downloads.
And that’s it! The first one can be the hardest, mostly because it’s unfamiliar and requires setting up an account and your API key. But once all that’s in place, it’s simple to create additional packages, and even simpler to push updates to an existing package (just make sure to increment your version number in the NuSpec file). Be sure to check out the source for AutoMapperPagedList if you have any questions, and if you feel like giving it a try in your projects, let me know!
P.S. – For a package that includes a web.config transform, you can check out the source for RazorScriptManager, another package I created that I’ll be blogging about soon.