Using SPWebConfigModification to modify a SharePoint web application's web.config for all servers in the farm

At some point in your career as a SharePoint developer you may find it necessary to push out a change to a SharePoint web application's web.config file for all servers in the farm. In the simplest of scenarios, it may be realistic to make the change to web.config manually, but if you are creating a packaged application for redistribution or there are many servers in the SharePoint farm, a better approach might be to make the web.config modifications programmatically. The WSS v3 API contains the SPWebConfigModification object which allows you to do just that. For example, if you have been following Daniel Larson's excellent series of articles on implementing AJAX in WSS v3, you know that AJAX requires an additional HttpHandler be added to a SharePoint web application's web.config in order to function properly. Here's the HttpHandler in question:

<add verb="GET" path="ScriptResource.axd" 
  type="Microsoft.Web.Handlers.ScriptResourceHandler, Microsoft.Web.Extensions, 
  Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
  validate="false"/>

To push out the AJAX HttpHandler declaration programmatically, the following example console application calls SPWebConfigModification. For the purposes of illustration, I've hard coded the web application's name ("Default Web Site"), but this could have just as easily been passed in as a command line argument:
12/28/2006 - MODIFICATION: Updated code listing with bug fix and added logic to remove the web.config modifcation.

Copy Code

using System;using System.Globalization;using Microsoft.SharePoint.Administration;
public class Program
{
    static void Main(string[] args)
    {
        string webAppName = "Default Web Site";

        // Add
        AddAjaxHandlerToWebConfig(webAppName);

        // Remove
        //RemoveAjaxHandlerFromWebConfig(webAppName);
    }

    /// <summary>
    /// Adds the Ajax HttpHandler to a web application's web.config for all servers in the farm
    /// </summary>
    /// <param name="webAppName"></param>
    private static void AddAjaxHandlerToWebConfig(string webAppName)
    {
        AddOrRemoveAjaxHandlerToWebConfig(webAppName, false);
    }

    /// <summary>
    /// Removes the Ajax HttpHandler from a web application's web.config for all servers in the farm
    /// </summary>
    /// <param name="webAppName"></param>
    private static void RemoveAjaxHandlerFromWebConfig(string webAppName)
    {
        AddOrRemoveAjaxHandlerToWebConfig(webAppName, true);
    }

    /// <summary>
    /// Adds or removes the Ajax HttpHandler to a web application's web.config for all servers in the farm
    /// </summary>
    /// <param name="webAppName">Name of web application</param>
    private static void AddOrRemoveAjaxHandlerToWebConfig(string webAppName, bool removeModification)
    {
        string assmDetails =
            string.Format(CultureInfo.InvariantCulture,
            "Microsoft.Web.Handlers.ScriptResourceHandler, Microsoft.Web.Extensions, Version={0}, Culture=neutral,
PublicKeyToken={1}",
            new object[] { "1.0.61025.0", "31bf3856ad364e35" });
       
        SPWebConfigModification modification =
            new SPWebConfigModification("add[@path='ScriptResource.axd']", "configuration/system.web/httpHandlers");
        modification.Owner = "Ajax";
        modification.Sequence = 0;
        modification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
        modification.Value =
             string.Format(CultureInfo.InvariantCulture,
             "<add verb=\"{0}\" path=\"{1}\" type=\"{2}\" validate=\"{3}\"/>",
             new object[] { "GET", "ScriptResource.axd", assmDetails, "false" });

        SPWebApplication webApp = SPWebService.ContentService.WebApplications[webAppName];
       
        if (webApp != null)
        {
            if(removeModification)
                webApp.WebConfigModifications.Remove(modification);
            else
                webApp.WebConfigModifications.Add(modification);
           
            SPFarm.Local.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
        }
    }
}

Real world use cases where this functionality may prove useful include calling SPWebConfigModification from a Window's Installer package Custom Action or perhaps extending stsadm with a custom operation.