Umbraco Caching Explained For Beginners - What Is the Umbraco.config?

Recently, I encountered an issue with an Umbraco site I've been managing. When one of the content editors published a blog article, it would appear on one node of the load balancer and not the other. Sometimes people would get a 404 when they tried to browse the Url's and sometimes it would load Ok. Due to the way Umbraco caching works this makes a lot of sense. In today's guide, I'm going to try and explain why this issue can occur by explaining some of the basics around Umbraco caching and in the process I'll explain how to resolve it.

Umbraco Caching

Umbraco provides several levels of caching. Like any .NET website we can use the output cache to automatically cache our website's web pages. Umbraco also introduces some additional internal caching in the form of memory and XML caching. The issue I mentioned at the start of the article involves the XML/file cache. If you want to look at this file cache, in your Umbraco webroots 'App_Data'folder, you should see a file called 'Umbraco.config'. Umbraco.config is used to improve the website's initial application start-up for things like IISRESETS etc.. As this file is used for improved performance handling you can delete it and your website won't blow-up. Umbraco.config is temporary generated, so in your website you can try to delete it, however, the next time someone tries to load your website, Umbraco will automatically re-create it. Obviously, it takes more processing power to re-create the file so performance will be affected if you continually deleted it, but you should hopefully get the concept.

How Does This Work?

Umbraco uses two types of cache internal memory and file cache. Under the cover whenever a node is published, or unpublished, Umbraco's internal memory cache is modified. As part of this change, the cache file (umbraco.config) is also updated. Having a file cache is great for performance because Umbraco only has to do a file read instead of a database query, so network traffic is reduced and performance is improved. Internal memory cache and XML cache should always be in sync. If you look in Umbraco.config, you should see a complete XML representation of your website's content. To make sure your website's using the latest version of a node you can look in here to make sure that the item in question contains the latest data. Umbraco can function and run without file caching as it's an optional feature. If you want to you can disable it. In your websites webroot, in the 'Config' folder, open up 'umbracoSettings.config'. In here you will find a setting called 'settingXmlCacheEnabled'. To disable file caching set this to false. With file caching disabled, Umbraco.the config file will not be updated anymore. Setting false in 'umbracoSettings.config' will ensure umbraco..config is ignored from now on (the file will still be written to though) If you want Umbraco to stop writing to 'Umbraco.config' altogether then there is also another setting in 'umbracoSettings.config' that you will need to be aware of, 'ContinouslyUpdateXmlDiskCache'. Some people get confused around these two settings. Setting ContinouslyUpdateXmlDiskCache results in the 'Umbraco.config' getting written to synchronously, or, asynchronously.

Umbraco Load Balancing Cache Issue

As you may have gathered, umbraco.config can cause an issue in a load balanced setup as your files and in-memory storage can vary per environment. The umbraco.config file is cached in memory after it's first loaded, so until each server's application pool is restarted, it is possible for the file to become out of sync and strange things to occur on your website. If you have a load balanced environment, then I would recommend that you read this. In my issue above with the load balancer, the node was being updated by a content editor. Umbraco.config was getting updated on one node. As the websites were set-up to not share the 'App_Data' folder, the site behaved differently depending on which node someone viewed the website. In my instance I had a few options:
  • Configure Umbraco to use a load balanced enviroment
  • Disabled File Cache
  • Share the App_Data folder between all enviroments
  • Use SugarSync
  • Write custom code to invalidate umbraco.config on all environments on node publish
As the site was developed before I joined the company, I went through the Umbraco Load balanced environment guide. In your web.config there's an option called, umbracoContentXMLUseLocalTemp. If this hasn't been set-up then you will definitely experience a lot of fun around different servers displaying different content. Instead of disabling 'Umbraco.config' setting umbracoContentXMLUseLocalTemp to use a local copy will also ensure each server uses a local version.
<add key="umbracoContentXMLUseLocalTemp" value="true" /> 


In today's post, we've mainly talked about Umbraco file caching, what it is, how it works and how you can configure it. When you work in a load balanced scenario, not having a strategy to deal with this file can result in strange behaviour, even resulting in 404 errors.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top