Managing Web.Config Customizations

I'm back after a long hiatus - international relocations tend to consume a lot of your free time - so it's time to start dusting off some of the many learnings I've had over the past few months...

One important topic I've encountered with my current and previous customers is how to manage web.config updates when deploying customizations. If you've been playing around with the Solutions framework, you're probably familiar with the ease of adding SafeControls entries to your web.config via your solution definition file, but what about all those other configuration settings that inevitably come up with SharePoint customizations?

In my research, I found three tactics for implementing generic web.config customizations programmatically:

  1. Install customizations in the \12\CONFIG directory as specified in the WSS SDK: https://msdn.microsoft.com/en-us/library/ms439965.aspx 
  2. Use the SPWebConfigModification class
  3. Manipulate the web.config file directly as an XML file (yuck!)

Based on the respective capabilities and level of effort associated with each tactic, I assembled the following matrix of tactics to customization scenarios - hope this helps!

 

Customization Scope

Method

Example

All zones for all Web Applications (Content web apps and Central Administration)

Create a solution with a webconfig.customizationname.xml file in the \12\CONFIG directory. See https://msdn.microsoft.com/en-us/library/ms439965.aspx for details.

Deploy this solution using an ApplicationServer deploymentservertype.

Execute the stsadm –o copyappbincontent command on all web application hosts (and the Central Admin host, if applicable) to apply retroactively to all existing content web application zones.

Notes:

· Do not execute the copyappbincontent command multiple times on the same server, as this can create duplicate entries of the customizations.

· You do not need to execute the copyappbincontent command to propagate the customization new zones/web apps.

A generic SPSite or SPWeb-scoped feature that is activated via a FeatureSiteTemplateAssociation.

All zones for all Web Applications (Content web apps only)

Create a solution with a webconfig.customizationname.xml file in the \12\CONFIG directory. See https://msdn.microsoft.com/en-us/library/ms439965.aspx for details.

Deploy this solution using a WebFrontEnd deploymentservertype.

Execute the stsadm –o copyappbincontent command on all web application hosts to apply retroactively to all existing content web application zones.

Notes:

· Do not execute the copyappbincontent command multiple times on the same server, as this can create duplicate entries of the customizations.

· You do not need to execute the copyappbincontent command to propagate the customization new zones/web apps.

A generic SPSite or SPWeb-scoped feature that is activated manually by a site owner/administrator.

All zones for selected Content Web Application(s)

Create a solution with a feature based on the SharePointDebugger feature. See https://blog.tedpattison.net/default.aspx for a detailed overview and https://tedpattison.net/downloads.aspx to download.

· FeatureReceiver.cs - Update the modification.Owner property as appropriate

· FeatureReceiver.cs - Update the Entries property to capture all required modifications. Be sure to use the correct SPWebConfigModificationType for each entry.

· Feature.xml –update the ID, Title, Description, ImageUrl, ReceiverAssembly, and ReceiverClass as appropriate

Deploy this solution using a WebFrontEnd deploymentservertype.

Activate this feature on the appropriate web application(s) via the stsadm –o activatefeature command.

An SPSite or SPWeb-scoped feature for personal sites (you did remember to put these on a separate web application, right?) that is activated manually by a personal site owner.

Selected zone(s) for selected Web Application(s)

A manual update is the best practice unless automation is absolutely required.

It is possible to update the web.config for a specific zone on all servers through code, but this essentially requires direct manipulation of the web.config files as XML documents.

Configuration settings for forms authentication providers.