Home > Upgrading > Upgrading a Customized Store
Upgrading a Customized Store
This page would welcome a sponsor from the AspDotNetStorefront community.
With proper planning and attention to detail, an upgrade with even a large amount of source code modifications can go smoothly.
This guide is broken down into 4 phases:
The more unknowns you can hash out during the assessment phase, the less chance there will be for surprises
when you deploy. If you plan courses of action for how to handle each customization, you can more accurately
estimate how long the local upgrade will take. If you keep your local upgrade separate from the live site deployment,
you can deal with issues before they have a chance to disrupt the live site.
Before performing an upgrade, you should do an upgrade assessment. Even if whoever handed you the upgrade swears up and down that it's version nine-dot-whatever and there has never been a source code modification.
Sometimes this person will be wrong, and if you have an estimate tied to the upgrade, that will also become wrong.
There are 4 things that an upgrade assessment will tell you, in order to prepare you for the task.
To begin the assessment, you will need:
Start the assessment:
You can often analyze a set of changes to group it into a single feature in your documentation.
For example "Custom Business ID field: AspDotNetStorefrontCore/Customer.cs, account.aspx, account.aspx.cs, createaccount.aspx, createaccount.aspx.cs."
Usually if there is a schema modification, it is tied to a specific feature, and you can list it there. However, sometimes you will find schema modifications that
have survived a feature that no longer exists, and you should still document it.
Your diff report and your documentation should paint a picture of all of the site customizations and their magnitude.
With each customization found in the assessment, there will need to be some questions asked:
Once you ask these questions of every customization you find, you can offer up options or recommendations. Here are some made up examples:
At this point you can probably see that if the assessment were skipped, the planning phase would either be non existent or willy-nilly.
If the planning phase is skipped, then the developer has to stop mid-upgrade when they happen upon a feature that needs a decision made by the merchant.
Or worse, they make the decision for the merchant, and then tell the merchant out of the blue that their upgrade is going to cost more, because of x, y and z.
Once a decision has been made on features that have multiple options, you will end up with a proper spec for the upgrade.
The developer knows what to expect, and the whoever is paying for the upgrade knows what to expect. Now people don't have to run around with their hair on fire, apologizing and panicking.
You should perform the first upgrade locally, in a development environment.
When you upgrade locally, you will do all of the merging of code customizations, and deal with any errors in the upgrade script.
You did the assessment and planning phase already, so you know exactly what you are going to do.
Make sure the fully customized, original site files (and source, if applicable) are installed locally.
Make sure you have the correct Encrypt Key from production, and that you have a database connection string to a restored backup of the Production Site ****Do not perform this upgrade on the production database itself****
You should be able to access this database from SQL Server Management Studio.
Run the website in Visual Studio (either through IIS express or the solution file), and make sure it matches production (you didn't get the wrong database, or the wrong files). Get a localhost license file if necessary.
After you've got it running and everything looks good, stop, and exit.
Make sure you have a clean copy of the latest version (including source, if applicable) installed and ready to go.
Copy the encrypt key and database connection string, and put it in the web.config file of the Clean Copy of the Latest version that you have ready.
Run the correct upgrade script (or series of upgrade scripts if applicable) on the database that you have backed up and restored from production.
If there are errors in any of the scripts, you are going to have to handle them on a case by case basis. In most cases, this won't happen. But, if there
was a particularly messy schema modification, you might have to alter the upgrade scripts. If you had an error, and you addressed it in the script, restore the database
with the backup again and start over until you can execute all of the upgrade scripts without an error. You will use the final scripts that work when you upgrade in production.
Make sure you have a localhost license for the version you are upgrading to, and place it in the latest version's images folder. Fire up the latest version
in Visual Studio, with the correct Encrypt Key and Database Connection String to the database you just upgraded. Now attempt to run the site. Unless the schema is extremely customized,
the site should run. You may see some errors about missing XmlPackages.
When you merge the customizations identified (in the assessment and planning phases), take care that you aren't just doing a diff between the old customized site and the new site.
You should only be merging the files that are a part of the customizations that you identified.
For each of these files, you should have either a three-way-diff or two separate diffs open of the out-of-the box old version vs. the out-of-the-box new version, and the out-of-the-box old version vs the customized old version.
If the file is completely custom, of course, you can just move it straight into the new version.
For the App_Themes & App_Template Skins, you'll want to make a quick diff beforehand. Of course the master.template is customized, but there might be some new things added. Like, version
9.4.0+ requires a block of code for jQuery. For the most part, you can just copy over the top of the App_Templates & App_Themes Skins with your customized ones. Copy over the top, but don't delete any *new* files in the skins.
For example, version 9.4.1 requires a css file named "base.css" that you don't want to delete.
After everything is merged, you should be able to build and run the site. Fix any build issues. If there are any runtime errors, address these as well. Make sure you can log in as an administrator, and successfuly create an order as a customer.
Each company is going to have it's own procedures for quality assurance. The more QA you do after your upgrade, the smoother your upgrade on production will be. At the minimum, you should stage your site somewhere that the stakeholders for the site (whoever is paying for the upgrade) can
test and make sure everything works as they expect.
Since you already upgraded locally, the upgrade to production should go smoothly.
You already upgraded the site files, so moving to production will be a matter of moving those files up and running your upgrade script(s).
Complete the following to prepare the deployment package:
Do not skip this step. Even if you think you got the latest copy of everything a week ago, get a copy right before you deploy. Remember that product/entity/topic images can be uploaded to the server at any time through the admin,
and you don't want to be responsible for losing someone's work. Backing up the live site files can take a little bit, so plan on doing this before bringing up a site down for maintenance page. When you schedule the
time to do the upgrade, make sure to start the backup of the site files at least 1 hour before the time you have scheduled so you can get it done in time.
Prepare a directory in IIS with a site down for maintenance page that you can temporarily point the website too. Most sites that have been around the block will
already have one that you can use.
You don't want to backup the database until *after* you have the site down for maintenance page up. This way, if you need to restore, your restore point will include any and all transactions
that happened while the site was still running. Create a full database backup (.bak) and make sure you know where it is located.
Before you proceed, make sure you completed all of the steps in creating the deployment package - especially the Encrypt Key and Database Connection String.
Run your upgrade scripts against the production database.
Once all files are in place and your database upgrade is complete, you can take down the site down for maintenance page and bring back up the upgraded site.
Make sure you can sign in as an administrator and see the admin console homepage.
Make sure you can checkout from start to finish and view the receipt.
Your upgrade is complete.