As Umbraco 4 is coming on Friday it's a good idea to start preparing upgrades. We've gone to great lengths to make sure that Umbraco is as compatible with Umbraco 3 as possible and Umbraco 4 includes an automated upgrade wizard that will convert any existing Umbraco 3.0.5+ installation to Umbraco 4, including converting your old templates to the new MasterPage syntax. For most installations, upgrading shouldn't be a problem and should take less than an hour.
In general it's very few items that aren't supported, but if you're using any of these features, upgrading is not straight forward:
- The XSLT helper method RenderTemplate(). As we've switched from the old proprietary template model in Umbraco 2 and 3 to ASP.NET MasterPages in Umbraco 4, the RenderTemplate can no longer be used. If your site depends on the RenderTemplate functionality, you need to disable MasterPages as continue to use the old template model which is still supported in Umbraco 4 by editing /config/umbracoSettings.config and set "useAspNetMasterPages" to false. It's crucial that you change this setting in the Umbraco 4 distribution before you copy the Umbraco 4 files.
- UltraSimpleMailer / Newsletter. This is not compatible with Umbraco 4 as it relied on a very old WYSIWYG editor and the old template model. We're working on making a new version of the UltraSimpleMailer, but it won't be ready for the release of Umbraco 4 on Friday. If you're using the UltraSimpleMailer we suggest that you don't upgrade yet.
- 3rd party datatypes. In general all old data types should work with umbraco if they're made using best practices. However, we can't give any guarantees that they'll work and you should make sure to test them first.
How to upgrade
First of all the upgrade wizard only supports Umbraco 3.0.5+ installations (while 3.0.3 installations apparently work too). If you're running an older version of Umbraco (2.0, 2.1 or <3.0.5) you should first upgrade to Umbraco 3.0.6.
Secondly, make sure that your site doesn't use any of the un supported functionality described above and if it does make sure that you follow the suggestions above.
Upgrade:
- Before you upgrade make sure to backup your files and your database and make sure that you run the upgrade on a local development server and not in a hosted environment.
- If you have special settings in your web.config or in your config files in the /config directory such as XSLT Extensions or localized url replacement characters, make sure to have those changes nearby as you'll need to update those settings after the upgrade. You might want to use a diff tool to see the differences.
- Extract the Umbraco 4 zip somewhere local outside your development environment.
- Copy the /web.config, /default.aspx, /bin, /config, /masterpages, /umbraco and /umbraco_client from the unpacked files to your umbraco 3 installation.
- Update the web.config and the /config files if you had any special settings (from step 2)
- Start a browser and point it to the root of your site (ie. http://localhost or http://mysite.com)
- Follow the installation wizard - it should upgrade your database and your templates automatically
If you have any troubles upgrading, let us know in the comments and if you encounter any bugs add them to the Codeplex tracker.