This guide covers upgrading to any version 9 edition of the AspDotNetStorefront software - ML or MultiStore. 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 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.
Depending on the version you are upgrading from, you may not have all folders mentioned below. This guide is written as broadly as possible to allow customers from any previous version to upgrade to 9x. The basic idea here is - nuke the '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 of the .NET platform.
1 - Download the new release from the AspDotNetStorefront Downloads Page
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 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.
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 doing this step, 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 web.config file has been re-encrypted.
5 - Open the web.config file in the new version's files, and modify the EncryptKey and DBConn lines to match those from the old web.config.
6 - Delete all of the files from the cloned copy of the old site, except /Addins, /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 /Skins, /Images, /Download, and /Descriptions folders to the location of the cloned install you created. If you are upgrading from an earlier v9 version, do not overwrite the /App_Themes and /App_Templates folders.
8 - Copy the files from the new version's /Web/Images folder but do not overwrite existing images! The idea here is to add in any new images that have been added since the version you're upgrading from.
9 - If you are upgrading to 9.3 or later, open the /App_Themes folder and find the Skin_2 folder within. That needs to be copied to your site, however the folder may need to be renamed! If you already have a /App_Themes/Skin_2 folder on your site, change the new version's folder to a different name (Skin_#) that does not already exist on your site and then copy that folder to your site. Then do the same for /App_templates/Skin_2. This new skin is for 9.3's built-in Mobile functionality, earlier versions can skip this step.
10 - If you are upgrading from an earlier 9x version and you were using Avalara, delete the /Addins/Addins/Avalara folder. Avalara has been converted to not be an addin anymore, so that folder is not needed.
11 - If upgrading from an earlier 9x version, copy the /App_Themes/Admin_Default and /App_Templates/Admin_Default folders to your cloned site. If your admin skin was customized previously, see the information on upgrading & customization 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) read/write/modify access to the AddIns 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 old database.
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,
then run "Update to 8.0.1.2", and then "Update 8.0.1.2 to 9.0.sql", 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 Downloads of your license portal)
15 - Follow the directions in the 'ASPDNSF Skin Conversion Guide' Word doc included in your 9.x build to convert your old skin to use master pages. (skip this step if you are already on a 9.x version)
16 - Open the cloned site in a browser and verify that it starts, and that the admin site is accessible.
17 - Remove the old .licx file from your /images folder, and replace it with a new key for the upgraded version. You can generate a new key at http://www.aspdotnetstorefront.com/mylicenses.aspx. See here for full licensing directions.
18 - Log into the admin site, 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. One for the admin strings and one for the front-end 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 - Adjustments to the skin may also 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
21 - 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, 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.
22 - Verify that all Security Best Practices are being followed on the upgraded site.
23 - If you are upgrading from a previous 9.x version to 9.3 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 tax will not be charged.
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 versions with little or no issues. If you do run into errors, most of the time it is simply do to the parameters an extension function is expecting being changed. 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.
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 extremely simple. Our support department can provide you with troubleshooting tips and advice, 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 your take a look for applicable entries to speed your installation process. If you cannot find an answer, please contact support (https://support.aspdotnetstorefront.com) for assistance.
The most common problem experienced during an upgrade is the database connection. This will throw a "DB Connection Failed" or AppConfig Table is NULL!!! error. The problem is easily resolved by verifying the connection string value in your web.config file is correct.
