How to create a Nuget Package by hand (without Nuget.exe or Nuget Explorer)?

Question

I've looked for descriptions of the files that go into a Nuget Package (.nupkg), but I have yet to find a definitive guide, most everything assumes you have to use Nuget Explorer, or the Nuget.exe -- but well, let's just say I'm obstinate.

Using the Nuget Explorer to create a package produces a directory with files that I'd like to create using a script or some other tool (besides Nuget.exe). So, given this simple directory layout generated by Nuget Explorer, I'm looking for definition of the .psmdcp file, the .rels file, the [Content_Types.xml] file, and of course the ProjectX.nuspec file.

I can find some details, or deduce them, for [Content_Typex.xml] and the .nuspec file. I tried making a package with just the lib/ dir, it's content, and a nuspec file, but apparently that isn't enough, and I get Package does not contain a manifest -- which I suspect means that the .nuspec alone isn't the full manifest.

lib/
  ProjectX.dll
  ProjectX.pdb
package/
  package/services/metadata/core-properties/____hash____.psmdcp
_rel/
  .rels
[Content_Types.xml]
ProjectX.nuspec

Is there no guide for making a .nupkg by hand? Is it really that complicated a process?

Answer 1

.nuspec defines properties about your package (the metadata) as well as a list of files to include in the package. There are plenty of descriptions of this around, so the bits that needs to be addressed are the files that are added by the tools:

.nupkg files follow the Open Packaging Convention. As you have figured out, it is really a .zip file with some predefined files. The _rels directory contain relationships between "parts". Think of a Word document containing images and Excel spreadsheet tables to get an intuition of "parts".

Packages mostly contain only one part; the package itself (but can probably contain sub-packages for modules). The _rels/.rels file defines the relationship for the main, top-level package. A relationship has an ID, a url that describes the kind of relationship and a target, which is the file which has this relationship to the package. Most packages has a relationship to the .nuspec file, which is of kind "manifest", and to the .psmdcp file, which is of kind "core-properties". The IDs of these relationships only need to be unique within the package, so they could be simply strings such as "R1", "R2", but for some reason they are "R" + 16 first bytes of GUID, in choco.

The core-properties seems to be mostly a rehash of the manifest file, dressed in Dublin Core tags instead of the nuspec; I guess in theory other programs could present the package based on these (if you embed it in a Word-document!). Probably psmdcp is an abbreviation of "Package Services Metadata Dublin Core Properties". Checking NuGet.Core/NuGet.Packaging/PackageCreation/Authoring/PackageBuilder.cs we see that the name of the file is a simply a GUID with "N" format (just digits). The lastModifiedBy property is the version information of the "choco" assembly itself; I guess you can really put anything there if you create the files yourself.

[Content Types.xml] defines the file format of extensions, in the form of MIME types. This is mostly boiler-plate.

So, in conclusion: Based on the .nuspec you can generate all the other missing files and put together the .nupkg yourself, even in a Powershell script.

Answer 2

I've written a blog post about how you could use the NuGet XSD: http://www.xavierdecoster.com/post/2012/03/08/Hidden-gem-the-NuGet-package-manifest-XSD.aspx

Also, take a look at the NuGet package conventions in the docs: http://docs.nuget.org/docs/creating-packages/creating-and-publishing-a-package#Package_Conventions

If you need more detailed hands-on, there's also a Pro NuGet book that goes in-depth into various scenarios: http://www.amazon.com/NuGet-Professional-Apress-Maarten-Balliauw/dp/1430241918