Upgrading an existing MonoX site to the new version can sometimes be a complex task as there are many areas that may been changed or customized between versions. These changes needs to be handled with care to perform an upgrade.

What is the procedure that should be followed to perform successful upgrade ?

Below are the sections that describe the general upgrade procedure that should be performed. Sections below are described in greater detail further down.

• Backup existing MonoX installation
• Get the version of the existing MonoX installation
• Download the latest version
• Examine the web.config file
• Copy the MonoX system files
• Perform the database upgrade
• Perform manual testing and run the automatic MonoX test
• Troubleshooting

Backup existing MonoX installation

The most important step of all is to properly backup your existing MonoX installation. These are the backup steps that we recommend:

• Backup your files from the root of the web site (You can do a xcopy of all your files, for more information about xcopy go here)
• Backup your database (for more information on how to backup database go here)
• It is a go practice to zip the files and database and to move it to backup server
• We advise you to perform the upgrade on backup copy of the existing MonoX installation not the live web site

Get the version of the existing MonoX installation

It is very important to get the version of existing MonoX installation because it will be used to properly upgrade the database. There are few ways you can find the version number and some of them are:

• Start your MonoX application using a browser and login with administrator credentials. After you are logged in you will see a small status bar at the top of the screen. In that status bar beside the other links you will see the current version number.
• Another approach is to navigate to bin folder using the windows explorer and scroll down to “MonoX.dll” file. Right click on that file and go to the properties. Here you will find a version tab (Windows XP and earlier) or details tab (Windows 2008 / Windows 7) where you can find exact MonoX version.

Download the latest version

To get the latest version of MonoX please visit the www.mono-software.com or use direct link and download it as zip file. Package comes with support for ASP.NET 3.5 (if you want to use ASP.NET 4.0 please read ReadMe.txt in the root of the package), so all you need to do is to unzip the files so we can examine the configuration files and synchronize the changes.

Examine the web.config file

In practice every MonoX installation has a set of custom settings (e.g. mail server, mail addresses, some third party tool accounts etc.) and depending on your configuration the changes may be found in more than one place. To identify all changes in your web.config file we advise you to use a DIFF tool like UltraCompare (http://www.ultraedit.com/products/ultracompare.html - Commercial) or WinMerge (http://winmerge.org - Free) to compare your web.config file with the web.config file from downloaded (latest) version of MonoX.

Copy the MonoX system files

In this section we will describe the steps needed to copy all MonoX system files to your existing MonoX installation. Before we proceed be sure that you have made a backup of live web site. The procedure described below will reference the backup instance and the downloaded instance of the MonoX (Note: It is not recommended to perform any upgrade procedures on the live web site).

• Remove old system files
  • Delete the “bin” folder in the root of backup instance (Be sure that you have zipped a backup copy before you delete
    the folder)
  • Delete the “MonoX” folder in the root of backup instance (Before you proceed please read the notes below)
    • If you have any custom content inside the MonoX folder please be sure that you have a separate backup of them (We advise you to move all custom content out of the MonoX system folder to your custom folder. Our practice is to create a folder in the root of the web site and call it by the project name. Then create a folder for every content type inside that folder e.g. Pages, Controls, WebParts, Scripts etc.)
    • If you have any custom web parts that you have placed in MonoX system Module gallery then be sure that you have a separate backup of them (We advise you to move your custom web parts out of the MonoX folder tree and place it under your custom module gallery which can be connected to a built-in module gallery whit application setting called “ModuleGalleryPath”)
    • If you want to retain your error, debug or info logs be aware that they are located at “/MonoX/ApplicationData/Logs” folder.
  • Delete the following template folders
    • Note: If you have modified existing templates than you need to skip this step and you need to sync the whole folder (We advise you to use DIFF tools mentioned above to sync the template files)
    • Delete the “Default” folder inside the “App_Templates”
    • Delete the “DefaultAdmin” folder inside the “App_Templates”
  • Delete the following theme folders
    • Note: If you have modified existing theme files or add new images than you need to skip this step and you need to sync the whole folder (We advise you to use DIFF tools mentioned above to sync the theme files)
    • Delete the “Common” folder inside the “App_Themes”
    • Delete the “Default” folder inside the “App_Themes”
    • Delete the “DefaultAdmin” folder inside the “App_Themes”
    • Delete the “Installer” folder inside the “App_Themes”
• Copy new system files (Copy the following from the downloaded MonoX instance)
  • Copy the “bin” folder from the downloaded instance to the root of backup instance
  • Copy the “MonoX” folder from the downloaded instance to the root of backup instance (If you have any custom content placed inside the MonoX folder be careful not to overwrite your custom content. Please read the “Delete the MonoX folder” section for more information)
  • Copy the following template folders
    • Note: If you have modified existing templates than you need to skip this step and you need to sync the whole folder (We advise you to use DIFF tools mentioned above to sync the template files)
    • Copy the “Default” folder inside the “App_Templates”
    • Copy the “DefaultAdmin” folder inside the “App_Templates”
  • Copy the following theme folders
    • Note: If you have modified existing theme files or add new images than you need to skip this step and you need to sync the whole folder (We advise you to use DIFF tools mentioned above to sync the theme files)
    • Copy the “Common” folder inside the “App_Themes”
    • Copy the “Default” folder inside the “App_Themes”
    • Copy the “DefaultAdmin” folder inside the “App_Themes”
    • Copy the “Installer” folder inside the “App_Themes”

Perform the database upgrade

Next step should be upgrading the database. We advise you to perform the database backup before you start the process described below. Now we need the MonoX version number that you have saved earlier so you could upgrade the database from that version to downloaded version.

• If you are about to execute upgrade scripts on live database we advise you to take the live web site offline so your users won’t get all sorts of errors (Unofficial recommendation from Microsoft can be found here)
• Folder that contains the upgrade scripts can be found in “/MonoX/Installer/Sql/UpgradeScripts”
• Find a subfolder that corresponds to the saved version number and start executing scripts from the next version subfolder to the downloaded instance version subfolder
  • Note: if any of the executed scripts fail please stop executing scripts and try to figure out what is causing a problem, or you can try to contact MonoX support department. If you do find what is causing a problem please make sure that failed script didn’t break your database structure before you continue executing rest of the scripts.

Perform manual testing and run the automatic MonoX test

After database upgrade is performed successfully it is time to perform few manual testing just to be sure that everything is working as expected. To do so you need to create a new web site under the web server you are using (this can be a subdomain, virtual directory, etc.) that points to the backup instance (which was just upgraded to newest version of MonoX). After you setup everything inside the web server try to load the backup instance with your internet browser. Here are the few major sections that we advise you to perform manual testing on:

• Initial web site load (Home page or your landing page)
• Now try to load section of your web site that contains following modules
  • User related modules (profile, avatars and similar)
  • Blog related modules (post list, post view and similar)
  • Group related modules (with groups you can test social networking wall, photo gallery and discussion module)
  • News related modules (main module, single news module, news menu and similar)
  • Discussion related modules (board list, topic list and similar)
• Login page (Login in as administrator)
• Load back-end administration home page (by clicking on the “Go to the portal administration area” located in a small status bar at the top of the screen)
• In the administration area you can test the following sections
  • File management
  • Page management
  • User management
  • News management
  • Blog management
• After you have performed all or some of the recommended steps above you can try to run MonoX automatic page test which can be located under back-end administration > Page management > right click on the Page grid > Test pages. It will crawl all the pages from the portal's SiteMap - by default, all pages that are visible in the navigation, along with the blog articles and user profiles are placed there.

Troubleshooting

In this section we will try to cover issues that may occur while upgrading to new version of MonoX.

• MonoXSearch module renamed to MonoXSearchResults (Apply only if you have custom usage of this module, if it is used inside the MonoX itself it will be upgraded atomatically)
• Namespace and class changes (Some older version of MonoX could have naming issues that should be solved by following the below instructions)
  • Remove all references to the “MonoX.Library” and point them to
    the “MonoX” (Note: web.config needs to be synchronized)
  • Change “<add expressionPrefix="Code" type="MonoSoftware.MonoX.CodeExpressionBuilder"/>” to “<add expressionPrefix="Code" type="MonoSoftware.Web.CodeExpressionBuilder"/>”
  • Change “<add verb="*" path="CaptchaHandler.ashx" type="MonoSoftware.MonoX.Captcha.CaptchaHandler, MonoX"/>” to “<add verb="*" path="CaptchaHandler.ashx" type="MonoSoftware.Web.Controls.Captcha.CaptchaHandler, MonoSoftware.Web "/>”
  • Change “<section name="Cache" type="MonoSoftware.MonoX.Caching.CacheConfigurationSec
    tion, MonoX"/>” to “<section name="Cache" type="MonoSoftware.Web.Caching.CacheConfigurationSecti
    on, MonoSoftware.Web"/>”
  • Change “MonoSoftware.MonoX.Helpers” to “MonoSoftware.MonoX.Utilities”
  • Moved “HTMLParseHelper.StripTags” to “MonoSoftware.Web.HtmlFormatter.StripTags”
  • All “*Parser” classes are renamed to “*Formatter”
  • Change “MonoSoftware.MonoX.Logger” to “MonoSoftware.MonoX.Utilities.LogUtility”
  • “WebParameterAttribute” is removed please use “UrlParam” class
  • “QueryParameter” is removed please use “UrlParam” class
  • Change “MonoSoftware.MonoX.Helper” to “MonoSoftware.MonoX.MonoXUtility”
  • Removed “Helper.FindControlInternal” function please use control extension method inside the “MonoSoftware.Web” namespace called  “FindControlRecursive”
  • Moved “MonoSoftware.MonoX.DataManager.DataManager” to “MonoSoftware.Web.DataManager.DataManager”
  • Moved “MonoSoftware.MonoX.Controls.RegExValidator” to “MonoSoftware.Web.Controls.RegExValidator”
  • Moved “HTMLParseHelper.FormatHtmlBreaks” to “MonoSoftware.Web.HtmlFormatter.EncodeBreaks”
  • Changed “SecurityHelper” to “SecurityUtility”
  • Removed “HTMLParseHelper.HideControlWithCss” please use extension method inside the “MonoSoftware.Web” namespace called“HideWithCss”
  • Changed “PagerHelper” to “PagerUtility”
  • Changed “UrlBuilder” to “MonoSoftware.Web.UrlBuilder”
  • “MonoSoftware.Core.Threading.ThreadPool” was removed from MonoSoftware Framework as an alternative we recommend the
    “Amib.Threading. SmartThreadPool” usage which is deployed with MonoX
  • Changed “LocalizationHelper” to “LocalizationUtility”
  • Removed “HTMLParseHelper.ReplaceAllValidTagsWithSymbols” - only in cases where the above is used in Url scenarios please use “MonoSoftware.Web.UrlEncoder.UrlDecode”
  • Removed “HTMLParseHelper.ReplaceAllSymbolsWithValidTags”
    • In cases where the above is used in Html / Javascript scenarions please use “MonoSoftware.Web.JavascriptFormatter.
      EncodeJsString”
    • In cases where the above is used in Url scenarios please use “MonoSoftware.Web.UrlEncoder.UrlEncode”
  • Removed “Helper.PrepareBucketSearchByPhrase” (You need to derive a custom “Base” class from
    “MonoSoftware.LLBLGen.RepositoryExtender” then use the “AddPartialPhraseSearch” method)
  • Changed “Helper.PrepareBucketSearchByPhrase(true, …)” (You need to derive a custom “Base” class from
    “MonoSoftware.LLBLGen.RepositoryExtender” then use the “AddWithOrPartialPhraseSearch” method)
  • Moved “Helper.GetSubString” to “MonoXUtility.GetSubString”
  • Removed LLBLGen “CustomExpression” please use the LLBLGen’s DbFunctionCall method
  • Moved “MonoSoftware.MonoX.Controls.GoogleMapsPanel” to “MonoSoftware.Web.Controls.GoogleMapsPanel”
  • Moved “UrlHelper” to “UrlUtility”
  • Moved “UrlHelper.ResolveUrl” to “UrlUtility. ResolveUrl”
  • Moved “UrlHelper. ResolveServerUrl” to “UrlUtility. ResolveServerUrl”
  • Moved “MonoSoftware.MonoX.Pages.Message” to “MonoSoftware.MonoX.Message”