Create and Deploy Sitecore Modules with NuGet
There are a number of ways for developers to move files and items between servers in Sitecore. The primary tools are the Package Designer and Installation Wizard that come out of the box. Other tools include Sitecore Rocks, Sitecore Serialization, and Hedgehog Development's Team Development for Sitecore.
Many .NET developers are probably already familiar with another tool for this - NuGet. NuGet is a package manager for the .NET framework. In this post, I am going to show you how to use, deploy and manage Sitecore modules with NuGet.
Most popular languages, frameworks, and environments have a package manager; the Node.js community knows the joy of "npm install RequireJS," Ruby developers know the ease of "gem install heroku," OS X has "brew install wget," and Python has "pip install lxml." Using a package manager encourages open collaboration and requires the library's developer to put in the extra effort to make that library consumable. As the primary reason to release a library, plugin, or module is to have it available to the community at large, the extra effort of packaging up a contribution is definitely worthwhile. Also, a Sitecore NuGet package has all of the advantages that NuGet offers.
Oh, the Reasons to use a Package Manager, Shall I Enumerate Thee?
Most package managers have the same advantages - let's discuss what I think are the three biggest:
- Canonical location: An official package repository lets the developer community know where to get the latest updates as well as all previously released versions. You can also include documentation, sample code, and whatever else may be appropriate for developers consuming your package.
- Version and dependency management: Is the latest version of package xyz dependent on a newer version of package abc? NuGet handles that for you when you update. You realize that there's a bug in the interaction between your code and package abc that you updated when you updated xyz and you want to downgrade package xyz? NuGet handles that for you as well.
- Lower barrier of entry: Those of you who have run a "gem install" or "pip install" know the difficulty of an install process that requires downloading all the necessary files and making the necessary references. It can be difficult enough to learn a new library, but at least package managers handle the boring installation process. Package managers also encourage developers to try a new library since the package manager also handles the uninstallation process if you want to bail out.
Since there is already ample documentation on the official NuGet site on NuGet functionality and a strong community around NuGet, I will focus on the Sitecore integration with NuGet rather than the standard NuGet functionality. You can find the original PowerShell scripts and their documentation on the Sitecore NuGet page for Sitecore Rocks. The method of retrieving these files is to install the NuGet package "Sitecore.NuGet.Sample." This is, in my opinion, not the best way of showing developers how to create your own Sitecore NuGet package because the division between the sample execution and the necessary tools for creating your own Sitecore NuGet package is unclear. The original documentation loads the reader with advanced details before the developer can execute a proof-of-concept, which can be discouraging. I was also unable to install the Sitecore files when I placed them in a "/external" folder indicated by the original documentation. With some decompiling, it looked like the Sitecore install scripts were looking in a folder named "wwwroot" instead. I have created a GitHub repo called Sitecore.NuGet.Skeleton which contains the basic folder structure and documentation on what goes into each folder.
git pull git://github.com/etruong42/Sitecore.NuGet.Skeleton.git
Before you package up these files using NuGet, you will probably want to remove/replace the original README.md files so your package will not install those files.
Creating a Sitecore NuGet Package
If you pulled the repo, you should see the following files (README files omitted):
The /content folder works like the usual NuGet content folder; this folder cannot be empty if you want the Sitecore-NuGet integration to function. I recommend including the typical Sitecore installation package for your module. This will allow your package consumers to use the Sitecore installation wizard to install your module. The /tools folder will contain the necessary PowerShell scripts for NuGet to install the package's Sitecore items and files. The Package.nuspec file is merely the default .nuspec file when you run "nuget spec," and this contains the necessary, typical NuGet package metadata that you will need to complete. The two folders that require special attention are the /wwwroot and /serialization folder.
- /wwwroot: you will place the Sitecore server files which you want to install in this folder. For example, if you create a /wwwroot/bin/MyLibrary.dll file in your NuGet package, MyLibrary.dll will appear in the bin directory of the Sitecore server.
- /serialization: you will place serialized Sitecore items in this folder. You can serialize Sitecore items by opening the Developer ribbon strip in the Sitecore Content Editor and using the Serialize Item and Serialize Tree buttons to serialize selected items. The item serializations will be saved to your website_root/data/serialization folder, and you will want to copy that folder to this NuGet /serialization folder.
Installing a Sitecore NuGet Package
Installing an existing Sitecore NuGet package will require two steps:
- Attach a Sitecore Rocks Connection to a Visual Studio Project using Sitecore Rocks by:
- Right clicking on the Visual Studio project to which you will install the Sitecore NuGet package, then clicking "Sitecore" and then "Connect."
- Connect using an existing Sitecore Rocks connection or create a new Sitecore Rocks connection to the Sitecore server where you want to install the package.
- John West walks you through this in his blog post.
- Install the NuGet package.
We can leverage Sitecore's PowerShell scripts to extend NuGet's functionality and better manage Sitecore packages. It requires effort to put Sitecore modules into NuGet packages, but there is already demand for these. My hope is that Sitecore NuGet packages will ease the lives of developers who must install, update, and manage Sitecore modules in any given Sitecore project.