Versioning your DotNetNuke modules - a quick guide

6. April 2010 22:55

When you start distributing your modules to other people you definitely want to version them. Mostly to keep your customers/clients/co-workers from going nuts when it's update time, and avoid the avalanche of support cases you will get if you don’t use versioned updates…
This is done by making sure the extension installation manifest contains the necessary info about what DotNetNuke should do when installing the package on sites where various versions of the module is already installed.
You can work half way to installation magic by knowing how to fiddle around with the manifest, and make quite complex installations. That is outside the scope of this post, though. I will talk about version 5 of the extension installation manifest from a module installation point of view. It will be kind of a basic case of module versioning, but hopefully it will get you started.
I have not found a really good reference on the version 5 extension installation manifest freely avaliable online, but Charles Nurse has written some pieces on the subject, well worth checking out:

The New Extension Installer Manifest – Part 1, Introduction
The New Extension Installer Manifest – Part 2, Component Installers
The New Extension Installer Manifest – Part 3, The Cleanup Component
The New Extension Installer Manifest – Part 4, The Assembly Component
The New Extension Installer Manifest – Part 5, The File Component
The New Extension Installer Manifest – Part 6, The Script Component

It has been in my mind a long time to put together some kind of more or less complete manifest reference, but have not gotten around to it yet.
I don’t in any way claim to be an expert on the subject, but I have found a practice that usually gets me around. Your feedback is most welcome.
Let’s get started.

As a starting point I'll use the manifest we got from my module development tutorial series. You can get the manifest here.
In this update scenario, imagine that we need to make a change in one of the stored procedures and that we want to add an image which will be used in the view control.

Database scripts

Add the file 01.00.01.SqlDataProvider to your module project. This file should contain the database scripts needed to change whatever needs to be changed from version 01.00.00. In our case it would be a script first removing the stored procedure, and then creating the new version of it.
When making changes to tables, it is very important not to drop the table and recreate it. If you do, you will very soon have your customers on the phone wondering why all their precious data went bye-bye when they installed the new version of the module.
Instead, alter the table. This often takes more work to accomplish, but it is the only option you have, really. Hopefully you think I'm silly even mentioning this kind of obvious thing, but I've seen it happen, so just in case...

Open up the manifest file and look at row 2:

<package name="Products" type="Module" version="1.0.0">

Change the version to "1.0.1".

In the scripts element, add a script element for the 01.00.01.SqlDataProvider file. The scripts section should then look like:

<scripts>
 <basePath>DesktopModules\Products</basePath>
 <script type="Install">
   <name>01.00.00.SqlDataProvider</name>
   <version>01.00.00</version>
 </script>
 <script type="Install">
   <name>01.00.01.SqlDataProvider</name>
   <version>01.00.01</version>
 </script>
 <script type="UnInstall">
   <name>Uninstall.SqlDataProvider</name>
   <version>1.0.0</version>
 </script>
</scripts>

When the extension is installed, the system will go through the scripts section looking for Install scripts. It will execute the scripts in version order, beginning with the first one having a version higher than what is installed. Scripts with a version lower or equal to the one already installed will not run.
Note that the script file names does not have to be the version numbers. I use it because I find it easier to see which version each script belong to.

When uninstalling the module, the script specified in the script tag with type set to UnInstall is executed.
If you create a manifest with DotNetNuke as described here, a version is specified for the UnInstall script. However, as far as I know, that version tag has no function. It works whether or not the version tag is there, or whatever version is set.

Files

In the files element, there should be a file element for each file to be copied into the module folder.
The simplest case is when the file is in the root of the package zip file. Then you use something like:

<file>
    <name>MyImage.png</name>
</file>

If the file resides in a subfolder you use the path element inside the file element. The subfolder will be created if it does not exist. So, if the name of the subfolder is images, you use:

<file>
    <path>images</path>
    <name>MyImage.png</name>
</file>

If the source file is not located in the same place as the target file, or if it has another name, you use the sourceFileName tag. For example, if the image file is located in the subfolder sourceImages in the installation package and has the name MySourceImage.png:

<file>
    <path>images</path>
    <name>MyImage.png</name>
    <sourceFileName>sourceImages\MySourceImage.png</sourceFileName>
</file>

 

Usually it doesn't get more complicated than this. Happy versioning!

Tags: , ,

DotNetNuke | Modules

Comments

4/22/2010 7:33:51 PM #

Vrtne garniture

Splendid blog! Its not often that I comment but I felt you deserve it

Vrtne garniture United States |

7/15/2010 6:36:26 PM #

Usman ur Rehman Ahmed

Thanks for this series of tutorials. I found them really helpful.

[ I am from Pakistan which is not in your countries list in comment section so I hope you will update that Smile ]

One question though which is related to your post of "Cleanup module", but I couldn't just post there since comments are closed.

When does the Cleanup component triggers? I just tested with a cleanup component placed at the end of the installed manifest and the rule base triggered during installation. I thought that would trigger when UnInstallation is made. So that suggests that one would have to install a separate extension to clean things up? Please guide.

Many Thanks

Usman ur Rehman Ahmed Saudi Arabia |

12/29/2010 9:54:13 AM #

Lipu

Thank you so much for writing up this tutorial. I started reading it yesterday and finished all of them today. Now finally I got the big picture of developing DNN Module and had my first DNN module - Product module.

Good work! Just curious, would you have time to do a DNN skinning tutorial?

Lipu People's Republic of China |

6/12/2011 7:26:25 PM #

Geo Neeliyara

Really, its a great article.....

Geo Neeliyara India |

5/17/2012 10:08:22 AM #

Tung

Great tutorial! I find this the best free DNN module development tutorial on the Web right now. Thank you very much. If you can, I would love to see you do a skinning tutorial. That would be best!

Tung Vietnam |

Comments are closed

About the addict

Johan Seppäläinen lives in Uppsala, Sweden. He spends most of his days working as a systems architect/developer, specialized in solutions built on Microsoft platforms.
Occasionally there is time for some recreational coding, when he pursues optimal solutions and code zen, mainly in C#. When he is not writing in this blog, that is.