How to: Create a Supplemental .config File

Applies to: SharePoint Foundation 2010

The %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\CONFIG folder contains .config and .xml files that are used together to create the web.config file for a Web application in Microsoft SharePoint Foundation. Before copying the web.config file from the \CONFIG folder to the root folder of the Web application, SharePoint Foundation searches the \CONFIG folder for any .xml file with a name in the format webconfig.*.xml and merges its contents with the web.config file. The actions defined in the .xml file are applied to the configuration settings of the Web application. A major advantage to using an .xml file to supplement the web.config file is that customizations are not lost when SharePoint Foundation is upgraded and the web.config file is overwritten.

Example

When saved as webconfig.myName.xml in the \CONFIG directory, the following example adds a safe control and replaces the run-time filter for the resulting web.config file that is created when a Web application is extended.

<actions>
   <add path="configuration/SharePoint/SafeControls">
      <SafeControl
         Assembly="System.Web, Version=1.0.5000.0, Culture=neutral, 
            PublicKeyToken=b03f5f7f11d50a3a"
         Namespace="System.Web.UI.WebControls"
         TypeName="*"
         Safe="True"/>
   </add>
   <remove path="configuration/SharePoint/RuntimeFilter"/>
   <add path="configuration/SharePoint">
      <RuntimeFilter
         Assembly="Company.Product, Version=1.0.1000.0, 
            Culture=neutral, PublickKeyToken=1111111111"
         Class="MyRuntTimeFilter",
         BuilderUrl="MyBuilderUrl"/>
   </add>
</actions>

The example adds a new SafeControl child element on the Xpath configuration/SharePoint/SafeControls, removes the RuntimeFilter element from the configuration/SharePoint/RuntimeFilter Xpath, and adds a new RuntimeFilter element on the configuration/SharePoint Xpath.

You can retroactively apply changes to the web.config files of the server by running the copyappbincontent Stsadm command-line operation. You must run the operation on each front-end web server in the deployment.

For general information about the web.config files used in a SharePoint Foundation deployment, see Working with Web.config Files

Warning

Changes that you make to any of the web.config files that are built into SharePoint Foundation, or that are created when a SharePoint Foundation Web application is created may be overwritten when you install updates or service packs for SharePoint Foundation, or when you upgrade an installation to the next product version. However, if you need to preserve changes through upgrades or updates, we suggest that you make changes to web.config settings using either the method described in this topic or the method described in How to: Add and Remove Web.config Settings Programmatically. With either method, your custom settings can be reapplied post-upgrade.

See Also

Concepts

Working with Web.config Files

How to: Add and Remove Web.config Settings Programmatically