NuSpec Manifests

The most versatile method of customizing a module package is by declaring a NuSpec (.nuspec) package specification.

The NuSpec file is an XML manifest that contains package metadata used to both build the package, and provide additional information to consumers. This manifest is always included in the final NuGet (.nupkg) package.

Manifest Schema

The following manifest represents the minimum required NuSpec (.nuspec) file structure to successfully build a Kentico module package.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>$id$</id>
        <version>$version$</version>
        <authors>$authors$</authors>
        <description>$description$</description>
    </metadata>
</package>

For a more detailed explanation see the official .nuspec schema documentation.

Replacement Tokens

As shown in the previous example, tokens such as $id$, $version$, etc. are automatically replaced by their defined value.

The following pre-defined tokens are available:

Token	Description
$id$	The case-insensitive package identifier.
$version$	The release version of the package.
$title$	The human-friendly title of the package for UI display.
$description$	The package long description for UI display.
$authors$	A comma-separated list of package authors.

The values of these tokens stem from module metadata defined in the Kentico admin or the replacement values declared by the -metadata and -version commands.

It is also possible to declare custom tokens through the -properties command as follows:

PackageBuilder.exe -module:Acme.Module
  -nuspec:Acme.Module.nuspec
  -properties:summary="Abstract summary here...",tags="Kentico CMS Module"

In this example, anywhere the $summary$ or $tags$ tokens are used in the NuSpec file, they will be replaced by the value declared in the -properties command.

Important: By design, pre-defined tokens cannot be replaced by the -properties command. These values must be explicitly overridden through the -metadata and -version commands respectively.

Including Additional Files

The NuSpec manifest also allows the ability to include additional files in the final NuGet (.nupkg) module package.

The following manifest will include a License.txt file and replace the default Readme.txt included by the native Kentico module export.

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>$id$</id>
        <version>$version$</version>
        <authors>$authors$</authors>
        <description>$description$</description>
    </metadata>
    <files>
        <file src="Acme.Module\Readme.txt" target="Readme.txt" />
        <file src="Acme.Module\License.txt" target="License.txt" />
    <files>
</package>

Note: File paths must be absolute or relative to the website root directory.