Search Descriptions Version
 
 
This article applies to: MultiStore, Developer Resources

Upgrading to a 9.x Version from earlier, legacy versions


The current software version as of 7/18/2014 is: Multistore 9.4.2.0

This guide covers upgrading to any version 9 edition of the AspDotNetStorefront software from any previous major point version (5.x, 6.x, 7.x, 8.x - but with the exception of DNN based versions). For instructions on how to upgrade from 9.x to 9.x, please go here.

The directions below include creating a backup/sandbox copy of the site on a local machine and upgrading that first before touching the production site. Upgrades should always be done this way! Upgrade a production site directly at your own risk!

IMPORTANT: Before making any changes to your live site, ensure that you have a full, working backup of both the contents of the site itself and the database!


It is also important to do a 'reality check' before starting a site upgrade. The day before a big marketing push or the height of the Christmas shopping season is not the time to do an upgrade. Though the process is not overly complicated, it needs to be done when there is time to work on it.

NOTE: Upgrading to version 9 is more complicated than previous upgrades, due to the large number of major changes that have been made to the application - especially to the skinning portion! DO NOT attempt this upgrade 'in place' on a live site or without giving yourself plenty of time.

NOTE: If upgrading from a version 8 software and you had FTS (Full Text Search) installed, you may get an error when attempting to search in the new version: Exception=The full-text query parameter for Fulltext Query String is not valid. It is highly recommended to first UNINSTALL the FTS in your version 8 site before upgrading the database to the version 9 software, where you can re-install the FTS if desired. Configuration - Advanced - Setup Full Text Search

Depending on the version you are upgrading from, you may not have all folders mentioned below. The basic idea here is - nuke the previous site 'stock' files and replace them with the new ones. Folders that contain your changed content (images, skins, etc) should be retained.

Procedure

NOTE: Versions 8.x and higher require version 3.5 SP1 of the .NET platform.

NOTE: These instructions ignore custom code modification considerations and describe basic upgrade steps necessary to upgrade a previous AspDotNetStorefront site to a newer version 9 platform. Any custom code modifications in the old site that you wish to retain will require merging or re-integration into the new software code by a knowledgeable developer.

NOTE: If you were encrypting the web.config on the site previously, you will need to log into the admin site, go to Configuration → Site Configuration Wizard, and change the "Encrypt Web.config" option to NO before cloning the existing site, or those keys will be unreadable. The .NET user account (typically ASPNET for WindowsXP or NETWORK SERVICE for Windows Server 2003/Vista or IIS_IUSRS for Windows Server 2008/Windows7) must be given Read/Write/Modify access to the folder the web.config file resides in. This is typically the {root} folder. Remember to reset the permissions once the unencrypted web.config file has been copied and the live web.config re-encrypted.

  1. Download the new release from the AspDotNetStorefront Software Downloads page in your license portal.

  2. Extract the files to a local machine. If your license does not include the source code, you should have 2 folders - DB and Web. Source code customers will see more folders. The contents of these additional folders should never be uploaded to a production site. Only the contents of the Web folder are necessary to run the site.

  3. Download all of the existing live site's files to a separate folder on the local machine, and obtain a backup of your current database from the host and restore it on the local machine. Refer to the Install Guides for directions on how to install the software on a local machine if necessary. Instead of creating a new database and extracting new files, you will be using the existing files and database to create a duplicate of the production site. The upgrade and testing will be done here, to minimize the impact on your live site.

  4. Once the cloned site is running, open the web.config file from that site and get the EncryptKey and DBConn values.

  5. Open the web.config file in the new version's files, and modify the EncryptKey and DBConn lines to match those from the cloned web.config that is running on your local/staged install.

  6. Delete all of the files from the cloned copy of the old site, except /Addins (through version 9.3.1.1), /Skins, /Images, /Download, /Descriptions, /App_Themes, /App_Templates, and any custom content you have created. This step is very important - DO NOT SIMPLY OVERWRITE THE EXISTING FILES!

  7. Copy the contents of the new version's /Web folder, except the /App_Themes, /App_Templates, /Images, /Download, and /Descriptions folders to the location of the cloned install you created.

  8. Copy the files from the new version's /Web/Images folder but do not overwrite existing images! The idea here is to bring over any new images that have been added since your previous version.

  9. If you are upgrading to 9.3.0.0+ from an earlier 9x version and you were using Avalara, delete the /Addins/Addins/Avalara folder. Avalara has been integrated and is no longer an Addin, so that folder is not needed.

  10. Copy the /App_Themes/Admin_Default and /App_Templates/Admin_Default folders to your cloned site, overwriting the existing files if any.

  11. For Skin upgrading and special considerations, please see the SKINNING section below.

  12. Give the .NET user account (typically ASPNET for WindowsXP or NETWORK SERVICE for Windows Server 2003/Vista or IIS_IUSRS for Windows Server 2008/Windows7/8) Read/Write/Modify access to the AddIns folder (through version 9.3.1.1) and Images folder.

  13. Connect to your cloned site's database using SQL Server Management Studio. The Express version is fine, and is a free download from Microsoft here.

  14. Run the upgrade scripts from the new version's /DB folder against the cloned database (be sure to backup the cloned database before each upgrade script is run!).

  15. NOTE: For all version 9 software upgrading to a newer version 9 release, just run the "Update 9.0 to Latest.sql" script.

    NOTE: Customers on versions earlier than 9.x will need to run multiple scripts. First you will run the appropriate "Update XXX to 8.0.sql" script to bring your site to 8.0.0.0 if necessary, then run "Update to 8.0.1.2", and then "Update 8.0.1.2 to 9.0.sql" (use this one also for ML8.0.1.4 and ML8.1.0.0), and finally "Update 9.0 to Latest.sql" (for upgrading to 9.2.0.0 there is a patched version of this script, available in the Software Updates of your license portal)

  16. Remove the old .licx file from your /images folder, and replace it with a new key for the upgraded version. You can retrieve a new key from your license portal. See THIS ARTICLE for full licensing directions (versions 9.1.0.1+), which are different than previous versions.

  17. Open the cloned site in a browser and verify that it starts, and that the admin site is accessible.

  18. Log into the admin console, and follow the "Reload from Excel file on Server" directions on this page to load the latest string resources on your site.

    NOTE: As of version 9 there are 2 files that need to be loaded with these directions, which are both loaded automatically with the "Reload from Excel file on Server" method. One for the admin strings and one for the front-end strings. BE SURE to select "Leave my modified strings" AND "Replace Existing". If you have multiple locales or are not using en-US, you may need to rename the new excel files in the \StringResources folder appropriately for your locale before reloading them, and also consider not selecting "Replace Existing" if your localized strings are not all considered "modified strings".

  19. Thoroughly test your site, to ensure that all functions are working as they should be. Product pages, admin functions, credit card processing - everything should be checked just to be safe.

  20. Once the upgraded cloned site is thoroughly tested and you are satisfied with the upgrade, you can REPLACE the live site's files (you made a backup first, right?) with the files from your 'cloned' site. Do NOT just overwrite the files! At this time download a current copy of the live database (it is prudent to set your live site as "down for maintenance" while this step is in progress), run the upgrade scripts and any custom modifications required, and migrate the upgraded database to the live site. Always retain a backup of the previous database.

  21. Verify that all Security Best Practices are being followed on the upgraded site.

  22. If you are upgrading from a previous 9.x version to 9.3.0.0 or higher and are using Avalara, your tax class codes may need adjusting. Verify that the tax class codes (Configuration->Taxes->Product Tax Classes) match either the tax class IDs in your storefront or the Tax Class Codes in your Avalara account, or set to "FR" , or tax will not be charged.

  23. If you are upgrading to a 9400+ version, be aware that the MaxMenuLevel AppConfig is utilized differently in the new skins and may need raised for proper display in skins older than the 9400 skin (MaxMenuLevel is "0" by default in 9400+).

Mobile Skin


  • If you are upgrading to 9.3.0.0 or later, find the /App_Themes/Skin_2 and /App_Templates/Skin_2 folders within the new version files. This new skin is for the 9.3.0.0+ built-in Mobile functionality. That needs to be copied to your cloned site, however the folder may need to be renamed! If you already have a Skin_2 folder on your site, change the new version's folders to a different numbered name (Skin_#) that does not already exist on your site, and then copy them to your site's /App_Themes and /App_Templates folders. Be sure to note which skin ID you set the mobile skin to so you can modify the AppConfig: Mobile.SkinId to match (set to "2" by default).
  • If upgrading to a version 9.0.1.3 - 9.2.0.0 and the previous version was NOT v9 software then be sure to review this article concerning the mobile skin functionality (MobileSkin_1)


Skinning and Special Considerations


There are special considerations you will need to understand depending on what version of skin you will be using:

PRE-VERSION 9 skin retained:
  • For converting your pre-version 9 skin to version 9.0.1.3 - 9.4.0.0 master pages, follow the directions in the 'AspDotNetStorefront Skin Conversion Guide.pdf' included in your 9.x build.
  • For converting your pre-version 9 skin to version 9.4.1.0 see this 9410 skin conversion guide.
  • If upgrading to 9.4.1.0 then Copy the file base.css from the new version's /App_Themes/Skin_1 folder to your /App_Themes/Skin_# containing your converted skin, as it contains necessary styles for the 9.4.1.0 components.
  • Copy the folder /App_Themes/Skin_1/images from the new version to your /App_Themes/Skin_#/images folder containing your converted skin, but DO NOT OVERWRITE any files, just merge any new images that are not existing in your converted skin.
  • Other adjustments to the skin may be necessary. In particular, check your site to see if text like ( !BUYSAFEJSURL! ) or ( !BUYSAFESEAL! ) displays. Those strings come from old skin tokens that were removed in 9.1.0.0. If those display on your site, you'll need to edit the template.master file and remove references to the token
  • Copy the folder /Web/XmlPackages from the new version to your cloned site, overwriting all existing xml packages. If you have customized xml packages you wish to use, you will need to merge your changes with the appropriate new xml package versions. We highly recommend having a knowledgeable developer perform the modifications.
  • If upgrading to 9.4.0.0 - 9.4.1.0 then Add this jquery reference to the head of your converted template.master file if you are using the Smart One Page Checkout (SOPC):

    <%-- jQuery is required in versions 9.4 and higher --%>
    <script src="jscripts/jquery.min.js" type="text/javascript"></script>
    <script type="text/javascript">
    adnsf$ = jQuery; <%-- to avoid conflicts with existing jQuery versions and other javascript frameworks, change this line to adnsf$ = jQuery.noConflict(); --%>
    </script>

  • If upgrading to 9.4.0.0 - 9.4.1.0 you will need to modify your template.master when adding the Google Remarketing per these instructions


Version 9.0.1.3 - 9.3.1.1 skin retained:
  • If upgrading to 9.4.1.0 then Copy the file base.css from the new version's /App_Themes/Skin_1 folder to your /App_Themes/Skin_# containing your retained skin, as it contains necessary styles for the 9.4.1.0 components.
  • Copy the folder /App_Themes/Skin_1/images from the new version to your /App_Themes/Skin_#/images folder containing your retained skin, but DO NOT OVERWRITE any files, just merge any new images that are not existing in your retained skin.
  • Other adjustments to the skin may be necessary. In particular, check your site to see if text like ( !BUYSAFEJSURL! ) or ( !BUYSAFESEAL! ) displays. Those strings come from old skin tokens that were removed in 9.1.0.0. If those display on your site, you'll need to edit the template.master file and remove references to the token
  • Copy the folder /Web/XmlPackages from the new version to your cloned site, overwriting all existing xml packages. If you have customized xml packages you wish to use, you will need to merge your changes with the appropriate new xml package versions. We highly recommend having a knowledgeable developer perform the modifications.
  • If upgrading to 9.4.0.0 - 9.4.1.0 then Add this jquery reference to the head of your retained template.master file if you are using the Smart One Page Checkout (SOPC):

    <%-- jQuery is required in versions 9.4 and higher --%>
    <script src="jscripts/jquery.min.js" type="text/javascript"></script>
    <script type="text/javascript">
    adnsf$ = jQuery; <%-- to avoid conflicts with existing jQuery versions and other javascript frameworks, change this line to adnsf$ = jQuery.noConflict(); --%>
    </script>

  • If upgrading to 9.4.0.0 - 9.4.1.0 you will need to modify your template.master when adding the Google Remarketing per these instructions


Version 9.4.0.0 skin retained:
  • If upgrading to 9.4.1.0 then Copy the file base.css from the new version's /App_Themes/Skin_1 folder to your /App_Themes/Skin_# containing your 9.4.0.0 skin, as it contains necessary styles for the 9.4.1.0 components.
  • Copy the folder /App_Themes/Skin_1/images from the new version to your /App_Themes/Skin_#/images folder containing your 9.4.0.0 skin, but DO NOT OVERWRITE any files, just merge any new images that are not existing in your 9.4.0.0 skin.
  • Copy the folder /Web/XmlPackages from the new version to your cloned site, overwriting all existing xml packages. If you have customized xml packages you wish to use, you will need to merge your changes with the appropriate new xml package versions. We highly recommend having a knowledgeable developer perform the modifications.


Version 9.4.1.0 skin used:
  • New Topics are used in the 9.4.0.0 and 9.4.1.0 version's base skins for many template elements, making customization of menus much easier. These are named Template.* and can vary slightly between versions. Be sure to use the style class references and IDs used in 9.4.1.0. You can view the "out of the box" 9410 template topic HTML contents HERE.
  • For the Bootstrap skin (Skin_3 by default), copy the xml package entitylist.xml.config from the 9.4.2.0 version App_Templates/Skin_3/XmlPackages folder to the Bootstrap (responsive) skin in your 9.4.1.0 skin.


For Customers with Customization
The difficulty in moving customization varies from build to build. If you have customized code in the web folder, it MAY be possible just to copy over the files that you made modifications to. The further you are between builds, the more likely it is that this will not work however. Make sure you test thoroughly.

If you have made changes to any of the compiled assemblies you must reapply those customizations and recompile in the new source files. The most efficient way to handle this in the future is to either add your code to custom classes or make sure you comment every single change with an easily searchable, highly descriptive comment. This will be invaluable if you have to change developers or wait months (or years) between upgrades.

XML package customizations also vary in difficulty. There is a good chance that your recent XML packages will transfer between similar versions with little or no issues. If you do run into errors, most of the time it is simply due to parameters being changed that an extension function is expecting. Simply copying the specific call to the extension function from a new XML package will often resolve any of these issues. If there are significant changes, it may be easier just to apply your modifications to a new XML package.

NOTE: A developer's guide has been created to assist with upgrading customized sites.


Troubleshooting Tips
Please keep in mind that AspDotNetStorefront has many different versions, and some versions are very difficult to upgrade from (particularly versions prior to 6.1) while others are fairly simple. Our support Help Desk can provide you with troubleshooting tips and advice (be sure you have subscribed to Year-Round Benefits before contacting the Help Desk), but it is not unlimited. If you are not comfortable performing some troubleshooting you should contact us to get a referral for someone that can help.

Many of the common errors you will run into during an upgrade will be logged in our knowledge base already. Make sure you take a look in this manual for applicable entries to speed your installation process.