SharePoint allows you to use SPWebConfigModification to programmatically make web.config changes which propagate across your farm. Typically, you do this by creating a SP feature and adding your code to its FeatureActivated and FeatureDeactivating event handlers. The advantage of this approach is that you can (ideally) keep the web.configs on your farm up to date and consistent without a lot of manual work. And if a new server is added to your farm, you (or even a sysadmin) should be able to update its web.configs by simply deactivating and reactivating a feature or two.
Unfortunately, SPWebConfigModification is scantly documented, difficult to use, non-transparent and notoriously prone to destroying your web.configs. After spending far too much time working with it, my advice right now is to avoid it like the plague. But if for some reason you decide to use it, hopefully this post will help you out.
So here are some of my observations/tips on the topic:
- SPWebConfigModification::Sequence seems to do nothing as far as I can tell. If you want to override the ordering on modifications, you should append [1=1] , [2=2] etc. to the Path. This makes no real difference to the XPath expression but takes advantage of the alphabetic ordering which is applied.
- When it comes to SPWebConfigModification::Type, do not use EnsureSection. This option creates web.config nodes which are are near impossible to remove. I tend to use EnsureChildNode.
- SPWebConfigModification::Name is actually an XPath relative to Path and is used to uniquely identify that node after it is added. Consider the below appsetting.
<add key="CachePeriod" value="300" />
We could add this node by creating a SPWCM and setting its name to add[@key=’CachePeriod’]. So now this node is uniquely identifiable by the combination of Path (its parent path) and Name (representing a node called Add with an attribute ‘key’ with the value ‘CachePeriod’. This app setting value could later be updated by applying an SPWCM with the same Path+Name and a different Value. If we didn’t want this appsetting to be updateable, we could incorporate its value in the XPath identifier.
- If you use SPWebConfigModification through a web-app scoped feature, be sure to disable auto activation. Because unless your WSP contains web-app resources, it may end up being deployed globally and if auto-activation is enabled, this will result in the modifications being applied to all of your web apps rather than the one you want to target.
- Don’t be surprised if any of the following occur:
- Race conditions
- SPWCMs being applied inconsistently across web app zones
- Modifications being ‘remembered’ by SharePoint, even after you’ve done everything you can to destroy them.
And if you’re still wanting to use SPWebConfigModifications after reading all of this, don’t say I didn’t warn you 😉 If you need discouragement, you need only look at any of the hundreds of blog posts written by disillusioned programmers who have been forced to jump through hoops in order to insert a bit of text and a few settings into their config files. The very existence of simulators and wrapper utilities for SPWCM attests to its nebulous and capricious nature, and in most cases, I’d advise that you save yourself the trouble and use WinMerge in conjunction with a canonical web.config.