Your SharePoint web.config and You

This post talks about the dos-and-don'ts of manipulating your web.config and explains some of the future ramifications of your actions.

Living a Double Life

Did you know that your SharePoint's web config is leading a double life? No, it's not having an affair or anything; it just has an apartment in the city for it's weekday gig and didn't happen to tell you.

That's right, SharePoint maintains its own version of the web config and expects the one in the Virtual Directory to match it. Any time it get's out of sync, SharePoint sweeps in and "fixes" it. Unfortunately, that fix might not be what you expect.

Here's what I've experienced.

What SharePoint Knows ... Goes.

I'm not going to go into how to use the SPWebConfigModification class in this post. If you want to know more about that, hop over the Dave Terrell's post about Using the SPWebConfigModification class in the SharePoint Object Model.

The quick story is this: if you make changes to your web config by using this class, be sure to only make updates to those changes using this class. Once SharePoint realizes something belongs in the web config, it will do everything it can to ensure that it stays there. If you make changes directly to the web config file (such as adding a SafeControl or a line to your appSettings block) it will be maintained until you manually remove it.

Changes made by SPWebConfigModification ALWAYS take precident over changes made manually. If you add an appSetting manually, SharePoint can remove it if an SPWebConfigModification says so. Unfortunately, if you add an appSetting using an SPWebConfigModification, removing it manually will only be an exercise in knowing how to navigate the file. SharePoint will simply add it back.

This can be painful to realize, but once you do, maneuvering around it is doable. It has caught me before... and I'm sure it will catch me again.