In this tutorial, you will learn about umbraco.config, what it is and why you might need to use it when you are working within a Umbraco CMS powered project. One important aspect of umbraco.config is caching 💨💨

Umbraco ships with a front-end cache out-of-the-box. This cache means when you need to query data about a page, instead of a database request being made, a much faster cache request is made instead. If you are not sure how umbraco.config works and you encounter a strange caching bug, it can be fucking annoying trying to resolve your issue (trust me 😊) This is why I think this tutorial will be of value to you. If you are currently experiencing strange Umbraco caching issues, or you simply want to master another aspect of Umbraco, this is the tutorial for you 🔥🔥🔥

How Caching Works Within Umbraco

Umbraco provides several levels of caching. Like any ASP.NET Framework website, we can use the output cache to automatically cache the response for any web page request. We have the Lucene index to speed up the search. Umbraco also ships with an internal cache to make its APIs quicker. This frontend cache is based on memory and XML caching. This file cache is managed with umbraco.config. You can access umbraco.config from within the App_Datafolder.

A useful thing to know about, umbraco.config is that it is dynamically generated so you can delete it without worry. You can test this yourself, delete it and load your site again. Umbraco will automatically re-create the file, magic 🪄

Obviously, it takes more processing power to re-create the file, so performance is slightly impacted on page requests where the file does not exist, however, if you encounter strange caching issues deleting this file might fix the issue 🤔

This situation happened to me recently on a project. The website was hosted within a load-balanced configuration. When a content editor published a blog article, the article would appear on one node and not the other. Sometimes site visitors would get a 404 when they tried to browse the Url and sometimes it would load Ok. By deleting the umbraco.config from the node 2 server, the page would become available.

The Umbraco internal cache relies on two forms of caching, 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 version within 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 cache is using the latest page content, you can look in here to make sure that the item in question contains the latest data.

Umbraco can function and run without this internal file caching enabled, as it's an optional feature. I'm not too sure why you would want to do this, however, you can disable the cache if you really want to 😱

Disabling the cache is done in config. In your website's webroot, within the Config folder, open up 'umbracoSettings.config'. Here you will find a setting called 'settingXmlCacheEnabled'. To disable file caching set this to false. With file caching disabled, umbraco.config file will not be updated anymore (the file will still be written to though).

If you want Umbraco to stop writing to Umbraco.config altogether, there is also another setting in 'umbracoSettings.config' that you will need to be aware of, ContinouslyUpdateXmlDiskCache. Setting ContinouslyUpdateXmlDiskCache to false will disable logging. ContinouslyUpdateXmlDiskCache can also be used to determine if the logs should be written synchronously, or, asynchronously.

Umbraco Load Balancing Cache Issue

umbraco.config can cause an issue in a load-balanced configuration, as the contents of umbraco.config 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.

TIP: If you host your site within a load-balanced environment, I recommend you read this

In the issue I mentioned above, the content editors changes were only being reflected in Umbraco.config on one node. As the websites were set up to not share the App_Data folder, the site behaved differently depending on which node a site visitor accessed. If you are encountering a similar issue, you have a few options:

  • Configure Umbraco to use a load-balanced environment

  • Disabled File Cache

  • use a shared drive and share the App_Data folder between all environments

  • Use SugarSync

  • Hook into the Umbraco events pipeline and write some custom code to invalidate umbraco.config on all environments on node publish

To solve my issue, I simply configured the site using the Umbraco Load balanced environment guide. Within web.config there's an option called, umbracoContentXMLUseLocalTemp 🤔

If umbracoContentXMLUseLocalTemp hasn't been configured, umbraco.config will not work correctly. Instead of disabling Umbraco.config, set umbracoContentXMLUseLocalTemp to use a local copy. You can make this change using this config:

Your load-balanced environment should now work like a dream ✨✨✨✨

You are now a umbraco.config BOSS 🏆🏆🏆. Understanding how these internal cache works is really useful when debugging the caching issues. I hope this tutorial has been of value to you, Happy Coding 🤘