KNOWLEDGE BASE

his is a pretty detailed guide of how to upgrade a version 3 Umbraco web application project to be version Umbraco version 4. Theoretically Version 4 is 100% backwards compatible with version 3. I've run a couple of upgrades and everything seems to work great. To upgrade an Umbraco 3 installation that is not part of your own web application project, it should be nearly the same, however you wouldn't need to worry about DLL references, etc.. as mentioned below. 

1. Download umbraco 4 binary files: Umbraco 4 Download
2. Backup Database
3. Take backup of all files for current version 3 install
   • If using source control might be best to create a branch
4. All of the Umbraco DLLs that your project is referencing need to be updated to the new Umbraco 4 DLLs.
   • Generally this means replacing the folder that contains your referenced DLLs with the DLLs in the bin folder of the Umbraco 4 download.
5. Update/Replace the "umbraco" folder's files:
   • If your project has not customized any of the files located in the "umbraco" folder, then just delete your original "umbraco" folder and replace it with the new "umbraco" folder found in the Umbraco 4 download.
   • If you project does have customized files in the "umbraco" folder, then it might be worthwhile running a diff on the files compared to the new umbraco 4 files to see what has changed and then manually make the changes to the new files to suit your needs.
6. Update/Replace the "umbraco_client" folder's files:
   • If your project has not customized any of the files located in the "umbraco_client" folder, then just delete your original "umbraco_client" folder and replace it with the new "umbraco_client" folder found in the Umbraco 4 download.
     • In most cases, files should not be modified in this folder
   • If you project does have customized files in the "umbraco_client" folder, then it might be worthwhile running a diff on the files compared to the new umbraco 4 files to see what has changed and then manually make the changes to the new files to suit your needs.
     • In most cases, files that have been modified in this folder have been done to modify the UI of the admin section (which requires a paid Umbraco license) or custom icons have been added to style tree nodes.
7. Web.config changes:
   • There are a few changes to the Web.config in umbraco 4 which may need to be manually merged in the AppSettings:
     • Change the value of the umbracoConfigurationStatus to be an empty string... otherwise the installer will fail to run.
     • The umbracoSmtpServer value is no longer used, Umbraco 4 uses the system.net -> mailSettings -> smtp values instead
     • The umbracoDisableVersionCheck is no longer required and can be removed
     • The umbracoVersionCheckPeriod should be merged from the Web.config of the Umbraco 4 download files
     • The umbracoUseSSL should be merged from the Web.config of the Umbraco 4 download files
     • The umbracoUseMediumTrust should be merged from the Web.config of the Umbraco 4 download files
   • The browserCaps section can be removed as the /config/browserCaps.config is no longer used.
   • The Umbraco membership providers must be added to your membership providers section if you have one, otherwise create the same membership providers section as seen in the version 4 web.config
   • The Umbraco roleManager providers must be added to your roleManagers section if you have one, otherwise create the same rolderManagers section as seen in the version 4 web.config
   • The Umbraco siteMap providers must be added to your siteMap section if you have one, otherwise create the same siteMap section as seen in the version 4 web.config
   • In the pages->controls section, you need to add the umbraco reference, this is important otherwise the new master page templates will not work.
8. All other files in the /config folder of your installation may need to be manually merged with the new versions of these files:
   • Don't overwrite your Dashboard.config, XsltExtension.config, formHandlers.config, 404handlers.config, metablogConfig.config, restExtensions.config, or your UrlRewriting.config files!!
   • If you've customized your tinyMceConfig.config then you will need to manually merge this file, otherwise, overwrite it with the new Umbraco 4 version
   • The umbraco.Settings file:
     • You'll need to merge the errors section if you want support for different error pages based on culture
     • The allowedAttributes property of the imaging tag has been updated to no longer support: title,hspace,vspace
     • The disableHtmlEmail property of the notifications section is no longer needed
     • By default the TidyEditorContent in Umbraco 4 is set to true (which uses a new version of Tidy)
     • The requestHandler section should be completely replaced by the new Umbraco 4 version (unless you've specifically made changes to this for your own reasons)
     • The templates section should be added
       • Please not if you set the useAspNetMasterPages to false, Umbraco 4 will still work (there's a couple of quirky bugs in the admin section with this but no show stoppers) but will be using the old Umbraco 3 templates. Setting this to true will automatically upgrade your templates to use master pages!
     • The logging section should be added
     • The webservices section should be replaced
     • The repostories and providers sections should be added
   • Replace the /config/splashes files with the new version 4 files.
   • Add the new App_Browsers folder
9. Replace the default.aspx file in the root of your project with the new Umbraco 4 default.aspx file
10. Replace the /install folder with the Umbraco 4 /install folder
11. Copy the Umbraco 4 /data/packages folder into your /data folder
12. Copy the master pages folder into your root directory 
13. Delete all DLLs from your project's output bin folder to ensure there are no old Umbraco DLLs hanging around
14. Attempt to rebuild your project!
    • If your project does not build, then this is most likely due to an error in your project, not Umbraco 4 DLLs. Umbraco 4 is 100% backwards compatible with version 3 and version 3 controls/packages
15. Run the installer: /yoursiteurl/install/
    • The installer should run seamlessly and you shouldn't need to modify anything
    • When prompted to install Runway, probably best not to do this on an existing installation

Some things to note after upgrading:

• Though Umbraco automatically created new master page templates for me, i had to manually add the
• I had to add a ScriptManager to my master master template as many of my controls relied on it. Umbraco 3 must have automatically inserted a ScriptManager
• It seems as though any public boolean properties that exist in user controls that get set via macros used to either have a 1 or 0 passed in to it which Umbraco would convert. With the new umbraco:macro control, true or false needs to be passed to it instead of 1 or 0.