The Pitfalls of Helix Projects and Kudu Zip Deploys

Kudu Deletes Things

Kudos to Kudu

If you're using App Services in Azure to host your client's websites, Microsoft provides a very powerful deploy tool: Kudu Zip Deploys. Kudu is somewhat unique over other deploy methods in that it is "intelligent". It has the ability to keep track of file changes, and it keeps your upstream file system clean whenever you remove files.

Kudu keeps a record of which files it manages, and which files it doesn't. For example, if you manually add files on the upstream server, Kudu won't touch them. However, it's the automatically managed files that you need to watch out for.

What if Kudu thinks you've removed a file but didn't actually intend to? Kudu will delete it, which may result in your upstream environment getting the yellow screen of death, or to become entirely unresponsive. This could very well require your manual intervention. There are two prominent cases: project references (DLLs) and web configs.

Project References (DLLs)

During local development you find yourself experimenting with code. You add some references that you don't actually end up using, but you don't notice this at the time. Some of the references are to Sitecore DLLs. Later on, you realize that you should clean up the unused references, and so you do. Local testing looks fine. Then you deploy and get the all too familiar yellow screen of death. Something about could not find type or Could not load file or assembly 'Sitecore.XXXXXXX' or one of its dependencies. The system cannot find the file specified.

What happened? Let's say one of the references you added was to Sitecore.Mvc.Analytics which you didn't end up using in your code. Then you deployed upstream. Kudu hooked onto that DLL, which would normally be sitting undisturbed in your /bin directory as part of the vanilla Sitecore install. But now it's disturbed because Kudu deleted it, because the reference you cleaned out was the only reference to that DLL, and given that nothing in your solution explicitly depends on it (though Sitecore does), that DLL is no longer included in your deploy artifact. In this case you'd have to manually add that DLL back to every environment you deployed to. Of course this won't always happen, depending on your build and deploy setup, but this is worth being mindful of.

Web Configs

Depending on your gulp build and deploy setup, web configs can be frighteningly easy to wreck during deploys. Particularly if you don't manage your upstream web configs in your code repo. As you're likely aware, projects have web.config files in order to help MSBuild do its thing. If your web config files are configured to copy to your build directory (commonly located at the root level and in the /Views folder), they can overwrite the web configs that have been specifically designed for Sitecore. This can result in your upstream environment becoming entirely unresponsive and can require a manual restore of the previous web config.

This is particularly applicable when you create a new project, forget to configure the web config deploy settings properly, deploy it, and then later on set the web config to not deploy next time. The web config will no longer be included in your build artifact. You can probably guess what happens next.


Be mindful of what you're referencing and what is included in your build artifacts. Kudu might just throw you a curveball.

Consider adding extra safety checks in your gulp build. One option may be to clean out any file types that you don't want to include in your build artifact, so that the upstream files can remain "unmanaged" by Kudu.

Good luck out there,


Hey, Developers!

We're on the look out for talented developers to join our team.

Think you have what it takes?