Managing Web.config Modifications

There are two common techniques for adding configuration data to the Web.config file:

• You can use the declarative approach and add sections of XML code to the file.
• You can use the SPWebConfigModification class to make the modifications programmatically.

The next sections describe each of these approaches.

Using the Declarative Approach

The declarative approach is best suited to situations where you need to add large amounts of XML code. In addition, all the configuration changes are applied to every application on the server. Any file that includes extensions to the Web.config file must begin with the webconfig prefix. The file must be deployed to the 12\Config directory.

The following is a sample file that adds a RuntimeFilter node as a child of configuration/SharePoint.

<actions>
   <add path="configuration/SharePoint">
      <RuntimeFilter
         Assembly="Company.Product, Version=1.0.1000.0, 
            Culture=neutral, PublickKeyToken=1111111111"
         Class="MyRuntTimeFilter",
         BuilderUrl="MyBuilderUrl"/>
   </add>
</actions>

The file describes where the extensions belong in the Web.config file and the actions that add the new nodes with the new configuration data.

To merge these changes with the Web.config file, you can either use the stsadm copyappbincontent command or you can use a Web service method ApplyApplicationContentToLocalServer().

This method locates the current Web service and merges the extensions into the Web.config file. Potentially, the ApplyApplicationContentToLocalServer method merges all configuration changes each time it is called. For this reason, the id attribute in the extension XML file must include a unique GUID so that existing changes are not merged a second time.

Calling the ApplyApplicationContentToLocalServer Web method or the stsadm command copyappbincontent command only merges the modifications on the Web front end (WFE) server where the method or command is called. It does not propagate these changes throughout the farm. You must use the copyappbincontent command on each WFE where you want the configuration data to be merged with the Web.config file. You must also use the copyappbincontent command each time a new WFE is added to the farm.

Using the SPWebConfigModification Class

The SPWebConfigModification class provides more control than the declarative approach. You can modify any node or attribute in the Web.config file. This means that the modifications can be as granular as you require. In addition, you can also target the modifications to a specific Web application instead of applying them to every application on the server.

In general, to use the SPWebConfigModification class, you should do the following:

1. For each configuration change, add an SPWebConfigModification instance to the WebConfigModifications collection of the current WebApplication object.
2. Invoke the Update method of the current WebApplication object.
3. Invoke the ApplyWebConfigModifications method of the current WebApplication object's Web service.

An example of using the SPWebConfigModification class is in the Contoso.LOB.Services.Client project, in the WebAppFeatureReceiver.cs file. The following code demonstrates how to programmatically add XML code to a Web.config file.

[SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
    //...

    SPWebApplication webApp = (SPWebApplication)properties.Feature.Parent;

    webApp.WebConfigModifications.Add(GetModification());

    webApp.Update();
    webApp.WebService.ApplyWebConfigModifications();

    //...
}

The FeatureActivated method adds the instance of SPWebConfigModification returned by GetModification() to the WebConfigModifications collection. The Update method applies the modifications to the SharePoint database. The ApplyWebConfigModifications method schedules a timer job to deploy the changes throughout the server farm.

The GetModification method creates an instance of SPWebConfigModification, setting the name, XPath, owner, type, and value properties.

private SPWebConfigModification GetModification()
{
    return new SPWebConfigModification("system.serviceModel", "configuration")
    {
        Owner = GetOwner(),
        Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode,
        Value = GetWcfServiceConfiguration()
    };
}

If you use the SPWebConfigModification method, modifications are added to the SharePoint database. A service on the farm named SPWebService.ContentService.ApplyWebConfigModifications applies the Web.config modifications to every WFE. (There is no corresponding functionality for deploying updates to layouts.sitemap.)

Home page on MSDN | Community site