Jumping the Hurdles of using SPWebConfigModification to Update the Web.config

In my Application Settings in SharePoint post earlier in the year I vowed that on any new project I would ensure that the web.config file would never be (ab)used with manual modifications to store application settings. I’m happy to say that I stuck to that goal, and this post is a reflection on my experience since of avoiding any manual intervention with the file. As I discovered there are a number of potential issues and gotchyas with using the SPWebConfigModification class including one particular bug which will be discussed later – it is important that one has read the numerous informative and valuable posts on the topic before endeavouring to ‘do things the right way’ when making updates or changes to the web.config.

You could be excused for thinking that with the myriad of issues that seem to exist when using SPWebConfigModification that it couldn’t possibly be a suitable method for making updates to the web.config. It is however generally considered a best practice and there is good reason for its use. Anyone who has studied for and sat the application development exam (70-576) would know that it is clearly positioned as the right way to modify values in the configuration file. It is listed as one of two available techniques in Managing Web.config Modifications, mentioned in the patterns & practices SharePoint Guidance in regards to adding entries into the web.config and referenced as one of the 10 Best Practices For Building SharePoint Solutions by having SharePoint Manage Custom Config Settings.

Rather than take it as gospel though there are some great posts out there that explain exactly why it should be used. One of the best is Charlie Lee’s What every SharePoint developer should know about the web.config file which sheds some light on how the web.config is pieced together while stressing the fact it should not be manually modified. Mark Wagner’s How To: Modify the web.config file in SharePoint using SPWebConfigModification, while being written for SP2007 and being a great resource in outlining exactly what SPWebConfigModification and its properties do, also discusses the advantage of having the class propogate your changes across the farm. Finally, Jonathon Le exposes some of the issues with making manual modifications in his post SPWebConfigModifications and Manual Config entries don’t mix.

But as I also mentioned in my Application Settings post, the internet is littered with issues and problems with using SPWebConfigModification. While this shouldn’t preclude its use, it’s important to understand everything that may go wrong and the things to pay particular attention to so any potential issues can be avoided. The first port of call here is Reza Alirezaei’s SPWebConfigModification’s Top 6 Issues. It highlights some of the common pitfalls that occur when trying to use it and how to work around them. One important thing to note here is a lot of the best resources around this topic were written for SharePoint 2007 and hence are not all still applicable in 2010, however a vast number of them still are.

So how did I implement it myself? As per numerous others I used a Web Application scoped feature with FeatureActivating and FeatureDeactivating event receivers to run the necessary code. MSDN’s How to: Add and Remove Web.config Settings Programmatically page proved reasonably useful however it’s important to note that the two code samples use different methods of applying the modifications – I adjusted the adding code to use the web application format present in the removing code. I also adjusted the removal code to ensure all modifications from a particular owner were removed, not just the most recent.

I was quick to learn however that using the Web Application scoped feature came with its own side effect – as soon as the solution file was deployed the feature was activated across all web applications automatically – not just the one I intended it for. A more in depth explanation and the resolution to this issue can be found at Waldek Mastykarz’s post Inconvenient SPWebConfigModification development with Visual Studio 2010 SharePoint Developer Tools and Nancy Brown’s SPWebConfigModification 2010: Change, Caveat, and Code – the latter also has a neat code sample on how to back up the web.config files before applying changes.

That wasn’t the only issue I ran into though. At one stage I was getting duplicate entries resulting in a configuration error when trying to load the site, and while I managed to resolve the reason for this on my own, was interested to see that Nancy had already documented the exact phenomenon in her article SPWebConfigModification Tool and Explorations under the How to Make the Removal Fail (or “How This Can Make You Nuts”) heading. This is another post worth reading as it includes a lot more valuable information within it.

The most intriguing issue overall however was the fact that my removal code didn’t seem to be taking effect although it was running without error and successfully removing the change from the modification collection. Essentially, it just wasn’t being reflected in the web.config. The change I had made was to add an attribute to an existing element within the file and while it added it fine it just wouldn’t revert back to its previous state after being ‘removed’. I stumbled across a couple of Technet forum posts; WebConfigModification Issues and Remove the web.config entries programmatically not working in sharepoint 2010 in which a Microsoft staffer, Rickee, indicated it was actually a bug in SharePoint 2010 and one which was not due to be fixed. He mentioned within those threads that it may be possible that while it visibly existed in the web.config file it may not have actually been taking affect – possibly a satisfactory conclusion to some but not something I was content with (as a side note, I never did end up testing whether that theory was correct – I wanted that attribute gone!).

I ended up coming up with my own solution – in the removal code I first applied another modification reverting the entry back to its original state, then ran the code to remove all modifications (including the one I had just run). This resulted in a clean modifications collection and a web.config entry which mirrored the initial value. While its not a perfect solution (that value could easily be set to something different in a subsequent version of SharePoint!) I figured it suited my immediate needs just fine.

As you can appreciate from this article there are a number of things you need to consider when modifying the web.config using SPWebConfigModification and you must take great care when doing so, lest you end up in a situation described in Michael Nemtsev’s post How SharePoint manages web.config via SPWebConfigModification! What’s important though is that you understand the risks and pitfalls but more pressingly understand the importance of using it to apply your configuration updates.

(Update: To see how SPWebConfigModification performs in SP2013, take a look at Using SPWebConfigModification to Update the Web.config in SharePoint 2013)