Manifests are configuration files that tell the DotNetNuke Installer how to handle items (or properties) during the Extension
Types of Manifests
With the release of 5.0, skins moved from being a simple zip file that had to follow some rigid conventions, to a true extension, the same as other add-ons such as modules and providers. Whilst skins can still be packaging in the legacy fashion, to make a DNN 5 skin that utilises extension capabilities, the skin developer must create a manifest file.
This has a lot of advantages;
- We can use one installer for all extensions
(people will have to get used to this, but in the end it will make installing extensions easier)
- DNN 5 Skins can have a version number.
- Skins can include a license text, release notes and the author is visible in the admin interface of DNN.
- You can create packages that install multiple extensions. This means you can package a skin object with a skin, as well as any containers you require. If a skin needs a specific skin object you had to instruct the user to download and install it separately in DNN 4, they can now be installed from one package.
To create a DNN 5 skin manifest
users need to define a Skin Component
. Whilst this can be done easily enough, a community member created an online utility
to simplify this process.
Often referred to as the DotNetNuke manifest file, this is a file that tells the DotNetNuke extension installer how to handle an extension package at time of installation. This manifest file is associated with the .dnn file extension. During extension installation, this file extension is changed to the .config file extension for security reasons (.config file extensions are protected by IIS).
As time goes by, the extension installer is enhanced and support is added for new things. Thus far, there have been multiple versions published. The most recent two, and the most popular used today: are version 3.0 (which supports DotNetNuke core 3.0 to 4.9, also available for use in DotNetNuke core versions 5.0 and greater) and version 5.0 (which supports DotNetNuke core 5.0 and greater).
The extension manifest contains multiple nodes, all of which play their part during extension installation. The area below explains each section, based on version 5.0 of the extension installer.
.dnn6 Extension Manifest File
As of DotNetNuke 6 (although not available in the CTP's or Beta) the ability was added to use a DotNetNuke 6 specific manifest file. This .dnn6 file can co-exist with the standard .dnn file so that the same extension package is install-able in a DotNetNuke 5.x version or DotNetNuke 6.x version. The primary reasons an extension provider would want to do this is if they want to take advantage of the module branding features or change the modal popup behavior but they are not quite yet ready to move all of their development over to 6.
The .dnn6 file manifest will also be read by DNN 7 and later versions.
Packages & Package
The DotNetNuke installer allows multiple packages to be installed with a single file upload (ie. zip file). Each package is declared independently of any other package and they are all contained within a single 'packages' node. Also worth mentioning here, almost all package data is stored in the core's Packages table. Example:
<packages><package name="1"></package><package name="2"></package></packages>
It should also be made known that each package equals one extension that can be managed in the DotNetNuke Extensions module, where they are grouped by extension type. The permissible extension types that exist in the core today are:
The list of extension types may also be expanded by developers. For example, the DotNetNuke Reports module adds the following:
- DNN Reports Data Source
- DNN Reports Visualizer
When declaring a package, you need to not only specify the name and the type but you must also specify a version. All of these properties (name, type, version) are declared in the package node's opening line and all are required. The name must be something unique and is almost never shown in the user interface (only when editing an extension as host can you see the name). DotNetNuke core extensions generally use DotNetNuke.x or DNN_x (where x is the extension name) so developers should avoid these. A general rule of thumb is to use YourCompany.ExtensionName when naming a package. The type property, available types noted in the list above, and the version property are used to determine how to handle the extension install. The version, for example, is referenced
The next two nodes within the package node are used to identify what the extension is called as well as what it does so it can be displayed to super users (or hosts). The first, friendly name, is how the extension will be referenced in the extension page. Friendly names can contain spaces and are permitted to have 250 characters. The description is self explanatory and you are permitted 2000 characters.
As of DotNetNuke 6.0, extension developers can add a node here named "iconFile" (after description, before owner which is discussed next). This node allows a custom branded icon to be associated with the extension. This icon will be displayed in the control panel's drop down list as well as the Extensions page (where all installed extensions are displayed). Please note, you must also include this image file (preferably of type .png) with your install-able extension.
From DNN 7.1 onwards, a new element has been added into the manifest, which denotes whether or not the extension has been tested and is compatible with SQL Azure. This is the element - which should contain a true or false depending on Azure compatibility. The correct usage is 'true' for being tested and compatible with SQL Azure, and false if it is not compatible. See Azure Compatible Extension Manifest Check.
The next set of nodes available are information about the extension author/owner and are nested within an 'owner' node. This owner section contains name, organization, url and email and although this information is not required, it should be provided.
After the owner section, there are two more nodes that should accompany every extension and they are the license and release notes nodes. Developers can either link to a file or include the notes inline for each of these nodes.
The final section, before diving into components, is the dependencies section. Each dependency must be listed as its own separate 'dependency' node, where a type property must be specified. The most common type used is the 'CoreVersion', where the minimum version of DotNetNuke core required to install the module is specified.
Supported Dependency 'type' values (NOT case sensitive):
- Compares value to current DotNetNuke version (see sample below).
- Compares value to the Name column from the core Packages table (see sample below).
- Dependency List Item (requires more info)
The example below is taken from the core forum module:
<package name="DNN_Forum" type="Module" version="04.06.00">
<description>The core forum module for DotNetNuke.</description>
<name>Forum Module Project</name>
An example of a dependency on an existing 'package' would be the following, taken from the MultiFunction skin found at http://multifunction.codeplex.com/
An example of a dependency on an existing package with a minimum version requirement, taken from jQueryMigrate found at GitHub
<dependency type="managedPackage" version="1.6.4">jQuery</dependency>
Although DNN does not expose a way to take a dependency on a particular .NET framework version, this can easily be emulated by taking a type dependency on a class that does not exist in prior framework versions. For example, to require .NET 4 as a precondition to installation, one may depend instead on the System.Tuple class (which was introduced with .NET 4.0):
There are a few things to be aware of when installing multiple packages within a single install (and thus, using a single manifest). First, packages are installed in the order they are declared in the manifest file (top to bottom). This means, if you are installing a skin extension that also contains a skin object, you need the skin object to be installed prior to the skin being installed (thus, placing the skin object package towards the top, above the skin package). In this example, the skin object was used by the skin being installed and therefore it needed to be available prior to the skin being installed (otherwise, the skin object would not be rendered properly).
Second, the installer user interface is only aware of the first package being installed. What this means is that only the information prior to the components section of the first package will be displayed during the installer screens (the name, description, owner information, license and read me notes).