Looking for the v10 manual? Visit our new user's guide!
Search Descriptions Version
This article applies to: ML8

Upgrading to an 8.x Version

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

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: 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 & 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.

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 /Skins, /Images, /Download, /Descriptions, 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.

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

9 - Run the upgrade script from the new version's /DB folder against the old database. The script will be named "Update x.x.x to latest.sql". NOTE: You will have several of these scripts in the /DB folder. Choose the one that matches your CURRENT version. For example, a site upgrading from 6.2 should use "Update 6.2.x to Latest" while a 7.0 site would use Update 7.x to Latest.

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

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

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

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

14 - Adjustments to the skin may also be necessary. For example, check your site to see if text like ( !BUYSAFEJSURL! ) displays. That text come from an old skin token that was removed in If that displays on your site, you'll need to edit the template.ascx file and remove references to the token.

15 - Once the upgraded cloned site is thoroughly tested and you are satisfied with the upgrade, work with your host to get the upgraded files and database 'pushed up' to your live site. This will generally mean FTP'ing the upgraded site files to your production site (remove the old files first, after making a full backup) and having the host restore your upgraded database.

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

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