# Wednesday, 01 December 2010

The basic process of updating uCommerce from one version to another is straightforward when you’re running a default setup: You install the new package on top of the existing one and uCommerce will figure out what needs to be migrated.

Database updates are handled automatically and will roll you forward without incident. XML files on the other hand are a little more tricky to merge so instead of trying to merge them uCommerce will overwrite existing config files with newer versions to ensure that the config matches the rolled out binary version of uCommerce; exactly as Umbraco does. This means that If you customized any of the uCommerce configuration files you will have to reapply those changes.

Not to worry though uCommerce will back up the files before resetting them. You’ll find the older versions sitting next the orignal file with a .backup extension.

Most of the time getting your settings back is a simple matter of copying back the backed up version of your configuration files and you’re done. The steps for manually reregistering your settings are outlined below.



Web.config is an interesting file because it’s used by Umbraco and uCommerce itself. During installation uCommerce merges its configuration with the existing web.config contents preserving any settings not owned by uCommerce, i.e. Umbraco, .NET, basically anything not known by uCommerce.

Connection Strings

During install the Umbraco connection string is picked up and added to the uCommerce configuration section to enable running uCommerce in a separate database. If you’re running with a separate database you need to point uCommerce at the other database once the update is complete.


Payment Method Services

Any custom payment method services for integrating payment gateways need to be registered in web.config. If you’ve created your own payment method service you’ll have to remember to reregister it once the update is complete. If you’re using the built-in ones you can omit this step. It’s important that you use the same name for your custom payment method service when you reregister it.

Payment method services are found in the <commerce> <ordersConfiguration> <paymentMethodServices> section in web.config.


Individual Payment Method Service Configurations

Each payment method service built into uCommerce comes with a configuration file. As these files are rolled out as part of the standard package install process they’re overwritten when you install a newer version of uCommerce. As with any other file you’ll find your old version of the file sitting next to the new one with a .backup extension.



Pipelines are basically XML configuration files which control the tasks executed in each pipeline and the order of execution as well. If you’ve added your own pipeline tasks to the standard uCommerce pipelines Basket, Checkout, ToCompletedOrder, ToCancelled, or SaveOrder you’ll have to add your custom tasks again after updating.

You’ll find the pipelines in the /umbraco/ucommerce/pipelines folder.


Components.config, Presenters.config, and XmlRenderings.config

All major components of uCommerce are configured in a central XML file, which lets you override any of the default uCommerce behavior by configuring your own components. While this is not the most common extension point used you’ll still have to reregister your custom components if you’ve extended uCommerce in this fashion.

Also web.config contains a reference to components.config in the <commerce> <runtimeConfiguration> which has to point at the correct file.

Presenters.config and XmlRenderings.config are referenced by Components.config and contains config for the UI pieces of uCommerce. Specically the backend (Presenters) and the frontend (XmlRenderings).

Wrap Up

uCommerce makes it very easy to update an existing installation provided that you’re running with a standard configuration. There are a couple of things you need to be aware of if you’ve customized the standard configuration files. This check list will make it easy to ensure that you didn’t miss anything when you update your existing site with a newer version of uCommerce.

Comments are closed.