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!).



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)

15. 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.


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


17. 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".


18. 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.


19. 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.


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


21. 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.


22. 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)

• 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

• 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

• 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.

• 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.