This wiki article is outdated and superceded by the documentation here:
The documentation link above is being maintained by the Umbraco HQ, the article below is not.
This article is currently lacking information about upgrading NuGet installs.
We're keeping the article below for historic reasons.
This page details the steps needed to upgrade an existing Umbraco site to a new version. Upgrading can be tricky as there are many areas that can have been changed on your current site, these changes needs to be transfered correctly to any new configuration files to have a graceful transition.
In what order to perform the upgrade?
This is the overall order an upgrade should follow, the steps below are described in greater detail further down
- Copy your current files and database to a new website, never upgrade a live site, you never know if something breaks, so do a full copy and upgrade that
- Get the latest version
- Check for package compatibility
- Examine your configuration files, the web.config, the files in /config and some other core umbraco files, look for any changes, preferably with a diff tool like http://winmerge.org/)
- Copy over all binaries and umbraco system files
- Transfer your config changes to the config files in the upgrade
- Open the root of your website, the installer should now launch automatically and perform the database upgrade.
Perform a backup
The most important part, always do a backup, and perform the upgrade on the backup, not the live site. So do a full xcopy of all your files from the root of your website, and a full copy of your SQL database.
Get the new version of Umbraco from CodePlex
contains the latest version of Umbraco, download it as a ZIP file.
(Umbraco versions 4.7.0 and above all require ASP.NET 4.0, but versions
prior to this come with support for either ASP.NET 3.5 and ASP.NET 4.0.
If so, select the appropriate version. If in doubt, ask your IT
administrator or hosting service.)
NOTICE: If you use the Windows ZIP utillity, remember to unblock the ZIP file so Windows security doesn't remove any files.
Unzip the upgrade files in an easy to find folder, as we in the next step will start to migrate your changes to these new files.
Check package compatibility
Some 3rd party packages might now be compatible with a new version of Umbraco. Check your installed packages list under "Developer / Packages" in the Umbraco backoffice.
Tested packages are located on this wiki page: http://our.umbraco.org/wiki/reference/packaging/umbraco-45-compatibility/umbraco-45-package-testing
If in doubt, contact the package owner
Examine your configuration files for changes
Before upgrading any files, you need to spot the areas where you've changed any default values. For some sites almost nothing has changed, and others there are mutliple changes. Depending on your configuration the changes can have happened in multiple files and folders. To capture all changes in your files, you can use a DIFF tool like WinMerge (http://winmerge.org) to compare your existing configuration with the default configuration files that came with your current Umbraco version.
For Umbraco version 4.0.x the process would be as followed:
- Get the files matching your current version from http://umbraco.codeplex.com
- Compare the.xml and .config files in the CodePlex folder with your current website config
- Winmerge can compare entire folder structures and filter by file-type for easy viewing
Now that you have a list of changes for your current version of config files, we can now compare that to the version you are upgrading to. So with your list of changes, compare these with the config files in the version you want to upgrade to; where changes makes sense, migrate the config change from your current site to the files in the upgrade folder.
When done, you should have a folder with all the new umbraco binaries, system files, and with configuration files matching your current site, and with any new configuration files.
Notice: By default Umbraco 4.5 uses a new XML schema, if you are upgrading from 4.0.x you either need to upgrade all your xslt files, or change a setting in the umbracoSettings.config file. This setting is called useLegacySchema and should be set to true like so:
<!-- to enable new content schema, this needs to be false -->
Optional: upgrade your xslt files to the 4.5 schema
If you wish to use the new XSLT schema in 4.5, but have legacy XSLT files, you can upgrade these with either of the following tools:
(neither of these tools guarantee to do a 100% accurate upgrade, so test the output and edit accordingly)
In case you use the new schema you should republishing your full site incl. all media, e.g. by using this command:
Copy the upgrade files to your website
Now it's time to upgrade, the below list of files and folders are copied to your current website folder (remember every time I say "your website" I mean the backup of you current website.
Files and folders to copy:
Overwrite all existing files and ensure that you gotten all your config file changes transfered.
Run the Umbraco installer to upgrade the database
When the files have been copied, open the root of the website. The Umbraco installer should now automaticly start and guide you through upgrading the database. your connection settings should already be correct as you migrated your changes earlier.
The installer needs permissions to run SQL create scripts, so ensure the connection to the database allows this. If doubt, ask your IT admin or hosting provider.
The final phase, check your packages and your custom code.
Errors could be caused by:
- A corrupted cache, which you can fix be forcing a re-population of the XML: http://yoursite/umbraco/dialogs/republish.aspx?xml=true
- A mismatch of your server's ASP.NET version and version of ASP.NET the assemblies use.
- Wrong XML schema which will break your XSLT macros.
- Missing files or wrong configuration files
- Incompatible packages, these can for example result in the tree in the back-office stop working, so make sure to test the compatibility first.
Also, you might have encountered an already know issue, please see this page for the most common ones, reported by developers:
If your upgraded site is not behaving as you expect, have a look at these two
Application Pool Settings
By default, Umbraco 4.5 uses the .NET 4.0 runtime assemblies and, unless you
have incompatible third-party controls or assemblies, we recommend your site use
this version. Frequently, when a site is upgraded,the associated Application
Pool is not set to use .NET 4.0. This is an easy change. To update your
Application Pool settings:
- From IIS Manager note the Application Pool your site is using
- Expand the Application Pools section and select the Application Pool noted
- Open the Application Pool’s properties dialog and set the following
- .NET Framework version: .NET Framework v4.* (from the Drop Down List)
- Managed pipeline mode: Integrated
- Click OK to save, and then Recycle the Application Pool to apply the updated
You may also choose to install Umbraco 4.5 for .NET 3.5, in that case select
the ‘.NET Framework v2.*’ for the Application Pool’s .NET Framework version
property value. However, we recommend using .NET 4.0.
ASP.NET AJAX Settings
While Umbraco 4.5 does not rely on ASP.NET AJAX many third-party controls use
this Ajax framework and you may have a version of the associated assembly
present in your /bin/ folder. If you do not need the ASP.NET AJAX assembly, we
recommend you remove it from your /bin/ folder, but if that was the case you
wouldn’t be reading this, would you?
You see 'Parser Error Message: Unrecognized configuration section
If you receive this error message when you access your site, please reference
the above section regarding Application Pool settings, as the most likely
scenario is that your Application Pool is set to use the .NET Framework version
2.* rather than .NET Framework version 4.*.
You have a dependency on ASP.NET AJAX
If you have controls of other code that depends on the ASP.NET AJAX framework
you can easily set these controls to use the .NET 4.* version of ASP.NET AJAX by
un-commenting the following section in your site’s web.config file, which should be included already:
<!-- Old asp.net ajax assembly bindings -->
name="System.Web.Extensions" publicKeyToken="31bf3856ad364e35" />
<bindingRedirect oldVersion="220.127.116.11-18.104.22.168" newVersion="22.214.171.124" />
name="System.Web.Extensions.Design" publicKeyToken="31bf3856ad364e35" />
This simply tells your controls to use the newer assemblies.
Running the Umbraco root from a fileshare on .net 4.0 results in empty content trees
Due to a breaking change in .net 4.0, running 4.5.1 on .NET 4.0 and with the site root on a fileshare, can result in all the UI trees being empty, this results in a exception message, like the one below:
"An attempt was made to load an assembly from a network location which would have caused the assembly to be sandboxed in previous versions of the .NET Framework. This release of the .NET Framework does not enable CAS policy by default, so this load may be dangerous. If this load is not intended to sandbox the assembly, please enable the loadFromRemoteSources switch. See http://go.microsoft.com/fwlink/?LinkId=155569 for more information."
A possible fix is to add loadFromRemoteSources to the web.config under <runtime/>
More information here: http://msdn.microsoft.com/en-us/library/dd409252(VS.100).aspx