Two important settings in Azure Web Apps that you definitely should care about are WEBSITE_DYNAMIC_CACHE and WEBSITE_LOCAL_CACHE_OPTION. Being careless with them can lead to either website updating problems or unnecessary performance degradation. I will explain why, and how you should handle them.

This is where you can set them in the Azure Portal. If you haven't added them, they will by default be WEBSITE_DYNAMIC_CACHE=1 and WEBSITE_LOCAL_CACHE_OPTION=Never.

Website Dynamic Cache Website Local Cache Option

The first time I saw the name of these settings, I thought they were about caching HTTP output (such as full web pages, web site contents, etc). Since I already had the HTTP output caching setup, I thought I didn't need to care about them.

I was totally wrong.

Then I ran into problems and found that the reason was my WEBSITE_DYNAMIC_CACHE and WEBSITE_LOCAL_CACHE_OPTION settings.

These settings are about your Azure Web App files. They decide where the files are written and read from your web apps.

Original Mode

Azure App Service files are stored on Azure Storage. Therefore the files can be stored pretty far away from your web server. They can be even in a different data center than your web app server. This of course slows down the file access.

  • All your web app instances share the same Azure Storage.
  • When publishing changes (for example from Visual Studio or CI/CD), they becomes directly available to your web app instances.
  • Reading and writing files can be relatively slow.

This is not the default mode!

To enable this mode, you must set WEBSITE_DYNAMIC_CACHE=0 and WEBSITE_LOCAL_CACHE_OPTION=Never.

Azure App Service Local Cache

Azure App Service Local Cache improves performance and web app uptime by copying your files to local storage. It does so by introducing a local cache on each web app instance.

More exactly:

  • When you web app starts, it copies the files from central Azure Storage to your local cache.
  • The local cache handles reads and writes, but the writes are never sent to the central Azure Storage.
  • When you restart your app, it will discard the local cache and reread the files from the central Azure Storage.
  • When publishing changes (for example from Visual Studio), they don't become visible to your apps until restarted.

This gives you much better file read/write performance for your website. It also means you get fewer restarts due to Azure Storage Share changes (but you need to restart after publishing your app).

Local Cache is useful if your website doesn't need to store any files permanently. In other cases, like Wordpress, enabling Local Cache is not a good idea.

To enable Local Cache, you set WEBSITE_DYNAMIC_CACHE=0 and WEBSITE_LOCAL_CACHE_OPTION=Always.

If you enable Local Cache, you can use the app setting WEBSITE_LOCAL_CACHE_SIZEINMB to adjust the cache size. By default the local cache is 1000 MB, but it can be increased up to 2000 MB. If your copied files exceed the local cache size, you may get no caching or an error.

Azure App Service Dynamic Cache

The Dynamic Cache is similar to Local Cache, with one major difference:

Files written by your web app will be persisted.

This means:

  • The dynamic cache handles reads and writes. The writes are sent to the central Azure Storage.
  • Other web app instances will get the updated files, but there is a delay (around 10 seconds).
  • When publishing changes (for example from Visual Studio), there is also a delay until it propagates to the web app caches.

This is very useful for web app performance. It also works with more apps than the Local Cache.

There are two possible modes for the Azure App Service Dynamic Cache:

  • WEBSITE_DYNAMIC_CACHE=1 means both files and their metadata are cached.
  • WEBSITE_DYNAMIC_CACHE=2 means only metadata is cached. This makes the cache much smaller, but you don't get the same performance increase.

Just be careful. It seems this setting can cause problems with some web apps. Also there is probably a limitation to the size of the cache, but I haven't found any documentation about it.

To enable Dynamic Cache, you set WEBSITE_DYNAMIC_CACHE=1 (or 2) and WEBSITE_LOCAL_CACHE_OPTION=Never.


Are you having trouble with your website not updating after you publish changes (from Visual Studio or other tool)? Do you have other strange problems with your website? Do you want to increase file access performance and have no need to write files persistently? Then try changing these settings.

Related Posts