The SPWebConfigModification Class: No, It Doesn't Suck

When I was working on my Hybrid Provider Installer, I came across a few things to discuss regarding the SPWebConfigModification class. One is a very minor SharePoint bug, and others are some nuances I ran into.

Now, of course, my code never has any bugs at all, ever, so I am vindicated to sit here and blog about the bugs of others. Just kidding. :)

Anyways, the aforementioned installer makes extensive use of the SPWebConfigModification class to programmatically modify the web.config files. An early cut of the installer used the standard ASP.NET System.Configuration and System.Web.Configuration namespaces to do the job. But I changed to using SharePoint’s API for two reasons. First of all, I want all my SharePoint code to leverage as many SharePoint APIs as possible.

But secondly, the SPWebConfigModification class will push its changes to all front end web server’s web.configs for a particular web application. This makes the installer work seamlessly for load balanced farms. Messing with web.config files is messy enough; worrying about having to synchronize these files across multiple machines is a borderline nightmare.

The bug I found is in the text of a SharePoint exception that the SPWebConfigModification throws. Unlike the ASP.NET API for this procedure, (which accesses sections and elements of the web.config file in a completely object-oriented manner) the SharePoint API relies heavily on XPath to access the different areas of the file. The jury's out on which one is "better" than the other (although object-oriented paradigms are usually the best in general) since both made some of the web.config modifications I had to perform trivial and others obnoxious.

The exception is thrown when the XPath points to an element that doesn’t exist. It also dumps out the absolute physical path to the web.config file in question. The problem is that the two are reversed in the message! Explicitly, the message reads (for example) as follows:

“Failed to apply a web.config modification to file ‘configuration/appSettings’. The specified node ‘C:\inetpub\wwwroot\wss\VirtualDirectories\80\web.config’ was not found in the web.config file.”

See the problem? The file name follows the node, and the node follows the file name! I know this is miniscule, but it throw me for a loop the first few times I encountered it. Regardless, I've submitted this to Microsoft as a bug.

Anyways, I've been reading some blogs about people who shy away from using this class. It is a bit clunky, but the fact that it propagates its changes through all web.configs in the farm made it real hard for me to pass it up. It's WONDERFUL to not have to worry about such things.

The one issue I did run into (other than the typo) was that it seems as though SharePoint "over-remembers" web config modifications. I'm not going to get into any code here since others have already documented it. But basically, each web application has a "living" list of web.config mods. When you create a mod and add to this list, it is applied. When you create the SAME EXACT mod and remove it from this list, it is undone.

The problem is that if you execute a bad modification, you must make sure to remove that exact same bad mod! If not, it'll get "stuck" in the web app's list of mods to apply, and be continuously applied incorrectly, allowing wrong and possibly mal-formed XML into your web.config. ALWAYS test these thoroughly in a development environment! Otherwise, not revoking the bad mod before fixing your code is essentially condemning your web.config to death!

Another issue is that people like to dabble in the web.config. At my last client, there were at least twenty different backups of the file in the virtual directory with names like 'web.config.old.july' and the like. And each one had all kinds of things commented out. The problem is that if you apply an SPWebConfigModification, then manually edit the part of the web.config you modified, then remove said mod, you might run into problems. So be careful!

But I said: despite its shortcomings, the fact that all changes are propagated server-wide for free makes it worth it! Have fun!