Hidden gem: the NuGet package manifest XSD

If you are automating the creation of NuGet packages (through CI for instance), you most likely touched a .nuspec file somehow. The .nuspec file is an XML file representing the NuGet package manifest, describing your package contents and metadata.

Creating the NuSpec

The most easy way of creating a NuGet package manually is through using the NuGet Package Explorer. It's simply a great UI on top of your packages and a good way of learning about some of the conventions that you need to follow in order to produce a valid NuGet package. It just works.

If you need to make big changes or want to add dependencies to other packages, NuGet Package Explorer is the preferred modification tool for these manifests. However, if you only need to modify the file very slightly, it's often faster to simply modify the XML. I'm sure many of us don't do this because there's quite a few options available and not everyone is familiar with the structure and conventions of this file. If only there was an XSD that could provide you with some Visual Studio Intellisense sugar… Hey, you know what, that XSD does exist! Actually, there's even more than one.

But why?

In the scenario of automation, there's no man in the middle that is going to click around in the UI for you, so you take a different approach. That's where the NuGet command line (nuget.exe) comes in. There are various ways of creating a package using the command line, and you don't always have to provide it with a nuspec file upfront (it can create one for you by deriving project or assembly information).

My preference goes to creating the package manifests upfront, manually, in XML. You have full control over its contents, and can create more advanced packages that simply cannot be created for you based on your assembly information, which provides a very limited amount of information. Put these .nuspec files in your VCS, and you have a versioned history on your package manifest modifications as well. Typically, I put them into the .nuget folder in my solution directory, which is created for you when you use the Enable-Package-Restore feature (also known as the no-commit rule).

I'm done reading, give me the XSD!

If you dive into the NuGet source code (and really, Codeplex, where's that code search box?), you'll find the XSD in the src\Core\Authoring\nuget.xsd path. Now, before you fetch it, remember I said there's more than one? Actually, the one you'll find in the sources is a template that changes over time (as new features are added for instance). The XML namespace actually contains a placeholder which is replaced during release. So *don't *use the file from Codeplex. You don't know whether it has changed since the last release.

To make things easier for you, I've done a look-up on the various XML namespace that are in use, and which version of the XSD matches. The end result is a NuGet package (what else?), containing the two XSD's and a sample .nuspec file to get you started.

Simply run the following command from the NuGet Package Manager Console and spend some quality time designing your package:

Install-Package NuGet.Manifest.Schema

The real benefit comes with Visual Studio's ability to automatically provide Intellisense for your file when it is declared in an XML-namespace it knows. For instance, when the XSD is available in your solution. Enjoy!