This question is related to this but not exactly the same.

From sitecore's recommendation its not good to modify the actual config files and always do it by patching.

I want to add a new hander which i cannot do it from patches as it should be added in web.config?

<add verb="*" path="project_sitemap.ashx" type="Project.Web.Handlers.Sitemap, Project.Web" name="project_sitemap" />

How can i add above line to <handlers> section with out modifying the default's sitecore web.config file. As this web.config file might be different in new version.

Sitecore version: 8.1 update 3

  • Have you tried using any of the approaches from the thread you linked? If something didn't work for you, please edit your question to include information on what it was. Dec 15, 2016 at 15:00
  • the accepted answer in that thread is asking to change the web.config as far as my understanding? which i want to avoid. Dec 15, 2016 at 15:01
  • @VladShpak yeah I read your comment wrong - deleted mine once I realized :)
    – Richard Seal
    Dec 15, 2016 at 15:25

2 Answers 2


While you cannot avoid changing the actual web.config file that will appear in the published /website folder of your site, you can make it so that you do not actually change the OOTB web.config file provided by Sitecore in your solution, by using config XDT Transforms.

If your goal is maintainability, and upgradability then this is the option for you.

Using XDT Transforms to insert your new handler

  1. Include a copy of the OOTB web.config file in your solution (which you could optionally make into a read-only file or just mandate that developers shouldn't change it).
  2. Add a transform file for the web.config file, which you can optionally nest under the web.config (e.g. web.transformed.config; some versions of VS require extensions to nest files with expand/collapse, e.g. the SlowCheetah extension, but that is OOS for this post).
  3. Set your transform files to actually transform on build (using VS build configurations, SlowCheetah, build events, or any number of other options) or on deployment to your build server (e.g. TeamCity) as a custom build step
  4. Add the necessary configuration to your nested transform file, including your new handler, with the necessary XDT Transform(s)

Your config transform (e.g. web.transformed.config) for this change would probably look something like the below (untested):

  <?xml version="1.0" encoding="utf-8" ?>
  <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
        <add verb="*" path="project_sitemap.ashx" type="Project.Web.Handlers.Sitemap, Project.Web" name="project_sitemap" xdt:Transform="Insert" />

Note that in the above, I used xdt:Transform="Insert" to add the new handler into the config.

Transform Strategizing

There are multiple ways to organize and execute your config transforms, and the strategy that you choose should help you determine how to name your transform files and what to include in each.

OOTB, Visual Studio supports transforms applied on build for each build configuration. The default build configurations for each solution in VS are DEBUG and RELEASE. You can add web.DEBUG.config and web.RELEASE.config transforms to be executed on build for the corresponding build configuration (i.e. if building in DEBUG mode then the web.DEBUG.config transform will be applied, where as if building in RELEASE mode then the web.RELEASE.config transform will be applied).

In contrast, Sitecore's config-patching feature is an example of a custom transform strategy that is executed on application start up. Conceptually, you could create a similar strategy that runs on build for all build configurations, wherein all configs that are configured as transforms would execute on build, regardless of naming, and you could use the names to identify the contents of the transform file rather than the build configuration that the transform file is applied for.

The sky is the limit with XDT Transforms, so start simple and figure out which strategy is best for you.


you just need to create a patch file that adds an entry to the <customHandlers> section. Something like this:

<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
            <handler trigger="-/sitemap/" handler="project_sitemap.ashx" />

Add that to your include folder and the part you already have to your web.config. There is no way to avoid changing the web.config file as you have to add it to the system.webServer section in there.

  • Thanks, I already got 'customHandlers' in my own patch file, just trying to avoid change in web.config file. If there is no way to do it with out changing web.config then that is what i need to do then. Dec 15, 2016 at 15:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.