The Short Answer
My usual response is: just like you would a new install. You go to “module definitions”, click “add new module”, select the module zip file (no need to do anything to that zip file first) and follow instructions on screen.
But this leaves implicit precautions to take when upgrading stuff in DNN. So I do mention at various places to “backup your DNN installation first". Because people only read warnings when things go wrong maybe it would help if I scared you about the consequences of not following this simple advice. To scare you I’d like to explain a little more in depth what happens during installation and what happens when that fails.
DNN Installer 101
Since way back when, DotNetNuke includes a piece of logic called “the installer” which unpacks an uploaded zip file and makes all necessary changes to DNN to incorporate whatever was uploaded. This is to this day I believe the most crucial piece of code in the extensibility of DNN. Without it we (module vendors) would be left with lengthy descriptions on how to install our stuff and you (the one installing) would need to have a PhD on how all this worked to the tiniest technical details. But the installer requires the zip to be packaged correctly of course, so that is our “craft” as module creators (note this goes for other extensions as well like skins and language packs).
Most importantly the zip file includes a manifest. An XML file that tells the installer what to do. Simplifying the process I’d say there are 2 major stages to the install: running SQL scripts and copying over files. The zip file contains both the SQL scripts to run and the files to copy and the manifest tells DNN what to copy where and which scripts to run. It is this SQL scripting which we will focus on here. Because the main difference between a first install and an upgrade is in the scripts. So here is where the key to “upgrading” lies. Let’s look closer at the scripts.
We create our stuff with scripts that are incremental. I.e. our first version comes out with version 1.0.0 of a script. We leave that file in every subsequent release package of the module. For release 1.1 we create a script that adjusts the database schema from version 1.0 to version 1.1. So we might create a table in version 1.0 of the script and add a column to that table in the version 1.1 of the script. This permits a package to both install anew and upgrade. And this is what the installer does.
The DNN installer knows if a module has already been installed because any module has a unique ModuleName in the manifest that it checks for in the Packages table. If found then it checks the version number of the installed module. Now it will proceed in “upgrade mode” meaning only those scripts will be run that have a version nr higher than the installed version (and of course they will be run in ascending order).
Failed Installs
Accidents have been known to happen. Murphy’s law dictates that if you’ve extensively tested your install on your staging site and you proceed to install on production something will break. This is shown as bold red text on your install report when installing a module. Now unfortunately you, as your client’s/company’s DNN person, will need to know a bit about how the installer works to get yourself out of this situation. The first step is analyze what went wrong naturally. This can break down into many categories. But the best thing is to make a copy of the install report first and save it! Then search the web on the error message.
Secondly you will want to know where the installer stopped doing its thing. The reason is that the installer does not sandbox the install. I.e. the install procedure runs the various tasks consecutively and in all likelihood it will have run some parts successfully before the error. The installer can’t roll back any changes.
Now at this point I need to point out that the behaviour of the DNN 4 installer is quite different from the (completely rewritten) installer in DNN 5. DNN 4 will, in general, attempt to continue after a failed task whereas DNN 5 will fail the install. In my opinion there is something to say for both. Let’s look at that a little closer. I’m going to add one more detail to the installation process: the module registration which comes at the very end. So the installer first runs a number of SQL scripts to update your database, then copies over files to various places in your DNN installation and then, finally, adds/updates a record to DesktopModules/Packages tables explaining to DNN that this module is installed and has controls XYZ. Let’s assume we have a fail in one of the SQL scripts. Now in DNN 4 the files would still be installed and the module registered. So there is a discrepancy between the module and the database where the module (both the dll in the bin folder that runs the module logic and the registered version on your module definitions page) is a higher version than the database version (which might be messed up badly depending on how subsequent scripts ran). The DNN 5 installer would not copy over files and would not register the new module. But some scripts might have run so in all likeliness you have a similar situation but now the module is probably of a lower version than the database.
The advantage of DNN 4 is that if the script fail was simple, the fix can be to simply run a bit of SQL under Host > SQL and all is well. The advantage of DNN 5 is that if the fail was somewhere in the middle of the bunch of scripts and subsequent scripts would have failed and messed up more then the situation is less complex. But in both situations chances are that you have a very complex riddle to solve and your site may be down for a lengthy period of time.
On numerous occasions in support we run into this and the most painful situations are those where the client has not even copied the install log. At that point we’re just left guessing what went wrong and where and unless the client has a lot of money to throw at it, this type of situation usually finishes by rolling back to the last backup. If this backup was not recent you can imagine the pain it causes.
Backing Up
Which brings me to backups. I mentioned Murphy’s law above and I should reiterate that although our stuff can be perfect and you may be perfect, IT is infinitely complex and unpredictable. We advise all our customers to make a backup before installing a module. A backup can be made quite quickly. Let me explain how.
As mentioned before, in general a module installation runs SQL scripts and copies over files. The file copying is usually done to two places: the module folder and the bin folder. This is a generalization but if you’re familiar with a module you will have an idea where the files go. It is certainly the case for Document Exchange. So a backup can be made as follows:
- Backup the Database
- Send the DesktopModules/Bring2mind/DMX folder to “Compressed folder” (i.e. zip it). It will create a zip under DesktopModules/Bring2mind called DMX.zip.
- Do the same for the bin folder of your DNN installation.
This does not need to take more than 10 minutes. And it will protect you from any fails in installations. Now, if anything happens (you see red text in the install report) you do the following:
- Copy the report from your browser to a word or text file!
- Bring down the site and recycle the app pool (this releases the hold the site has on the database)
- Restore the database
- Delete the DesktopModules/Bring2mind/DMX directory and unpack the previously zipped version of this folder there.
- Do the same for the bin folder
- Bring the site back online
This is also 5 to 10 minutes work
Now you have (1) an error report, (2) a running site and (3) a backup still in place in case you want to try again.
Final Remarks
I had to roll back twice installing my very own Document Exchange on my very own Bring2mind site. On both occasions I ran into obscure quirks of the DNN 5 installer. Luckily I followed the above method so I could keep working the problem instead of digging an even deeper hole. In so doing I realized that if this can happen to me (supposedly I’m a DNN expert) it can certainly happen to you. I hope this post helps to prevent you getting yourself into real trouble and not just with installing DMX.
A final note and disclaimer on other modules. It is possible for modules to have files copied to other places than the module and bin folders. Also, because they can run code after install, they could even alter stuff in the portals directory. The approach above works for most Document Exchange upgrades. If you want to be absolutely 100% insured against mishaps then make a complete backup. This means a database backup and copying the complete DNN installation. Also, when copying back a backup make sure that disk permissions are what they were before. This approach is bulletproof as far as I know.