Create a nuget package (for an episerver gadget)

Creating a nuget package is not difficult. It is just so many possibilities so that you don’t know where to start. In this post I will create a very basic package that can be used as a base for further projects, especially when developing episerver edit mode gadgets to be available in nuget galleries. Some of the common optional elements of a nuget package will be also be explained. In this post, a package for an episerver gadget described in another post is created.

.nuspec to .nupgk

Creating a nuget package is done using the command line tool nuget.exe. Nuget.exe doesn’t come with visual studio and can be downloaded from https://www.nuget.org/downloads. The nuget pack command will take a .nuspec file as input and produce a .nupkg file, that is, a nuget package. The .nuspec file is a text file with xml content and is either the result of running the nuget spec command or it is written from scratch. nuget spec can create a .nuspec file based on either an assembly dll or a VS project. The resulting .nupkg file is technically just a zip file and to view the contents of a package, simply replace the .nupgk extension with .zip and extract.

Here is the .nuspec file for our package

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
<metadata>
    <!-- Required metadata elements -->
    <id>BlockFinder</id>
    <version>1.0.5</version>
    <description>Find blocks within a page in episerver edit mode</description>
    <authors>Lars Waernulf</authors>

    <!-- Optional metadata elements -->
    <projectUrl>http://www.waernulf.com/</projectUrl>
    <tags>blocks add-on edit mode composer episerver</tags>
    <dependencies>
    <dependency id="EPiServer.CMS.UI" version="9.9.2" />
    </dependencies>
    
</metadata>
    
<!-- Optional 'files' node -->
<!-- src is source but target is special -->
<files>
    <!-- target="content\myfile.txt means file in src will be copied to {project root}\myfile.txt -->
    <file src="..\..\alloy11mvc\BlockFinder\BlockFinderComponent.cs" target="content\BlockFinder\BlockFinderComponent.cs" />
    <file src="blockFinder.zip" target="content\modules\_protected\blockFinder\blockFinder.zip" />
    <file src="web.config.transform" target="content\web.config.transform" />
    <!-- this combination of src and target will show the content of readme.txt after install -->
    <file src="readme.txt" target="" />
    <!-- to add a dll, use target="lib\..." as shown below -->
    <!-- make sure the framwork version, here net461, matches the target framework setting in the project where the dll is build-->
    <!--file src="..\..\alloy11mvc\bin\alloy11mvc.dll" target="lib\net461" /-->
    <!--file src="..\..\alloy11mvc\bin\alloy11mvc.pdb" target="lib\net461" /-->
</files>
</package>

.nuspec elements

Inside the root element package, there is one required element, metadata, and an optional element, files. The id element inside metadata has to be unique within the gallery. The dependency element lists dependencies to other nuget packages. Packages listed under dependency will be downloaded and installed if they are not already in the project the package is being installed into.

<file>

The file element inside the files element specifies file(s) to be included in the package. The file element has two attributes, src and target. The src attribute points to the source file(s). Wildcards are allowed. The target attribute is special. If you use a convention based working directory, no files have to be specified at all. You can read more about conventions, the target attribute and other details of the .nuspec file here https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package

Verify and Upload

Nuget package explorer is a valuable tool. It can be used for inspecting nuget packages. This is useful when developing your own package. The tool can open packages for inspection (without installing them) from the local disc as well as from nuget galleries. The tool can be downloaded from Microsoft. Browser/firewall issues forced me to look for another download location which I found here. I used google and this service check the reputation of the location.

Next step is to install the nuget package into Visual Studio from a local package source, i.e. a local disc. Open Nuget Package Manager in Visual Studio, create a new package source by pressing a button next to the package source drop down, choose the location of the created nuget package as the location of the new package source and install the package. After testing installation and removal, publishing a package to nuget.org is done simply by uploading the .nupkg file (you must sign in with a Microsoft account).

Developing and packaging an episerver edit mode gadget

Most people probably think of nuget packages as a way of distributing already built code, as assembly dll(s). An issue of concern is that you don’t know what is inside the dll(s). With a signed package, you can at least verify who the author is and decide which authors you want to trust. In this package, which isn’t signed, no dll is added. The very few lines of server side code have to be compiled with the project.

The files used for creating the package were put together in a project in the same solution as an alloy site project on which the gadget was developed and tested. In Visual Studio 2015 there is a project type called shared project that was suitable. The project type does not come with any default files or logic that have to be removed.

The Episerver framework together with the default configuration lets you install gadgets or modules in the format of a .zip file. It’s just an option and the by Episerver included modules are installed that way. It has advantages when it comes to version control. The module can be unzipped after being installed if content needs to be changed or added, the module will still work as before.

The package is created by open a cmd window, navigating to the BlockFinder folder and typing build. Before that, the folder c:\nuget\ has to be created and 7zip has to be installed. Here is the cmd script, build.bat, that builds the package.

del BlockFinder*.nupkg
del BlockFinder.zip
"c:\program files\7-zip\7z.exe" a -mm=Deflate BlockFinder.zip ..\..\Alloy11mvc\modules\_protected\blockFinder\*
nuget pack -Verbosity detailed
copy BlockFinder*.nupkg c:\nuget\*

A file with the .transform extension contains transformations that will be applied to a file with the same name except the .transform extension. I.e. web.config.transform contains transformations that will be applied to web.config.

<?xml version="1.0"?>
<configuration>
    <episerver.shell>
        <protectedModules>
            <add name="blockFinder" />
        </protectedModules>
    </episerver.shell>
</configuration>

Be careful not to install the package in the same project it was developed in.