Project Description
Make SharePoint web config modifications using a config file, rather than having to hard-code static strings in a class file.

While SharePoint provides developers with an API to manage web.config modifications, those entries are commonly managed via custom, hard-coded Features or stsadm commands, which means packaging and deploying code to run and test changes. And, to top it off, SPWebConfigModification is not the easiest object to use, and takes a little bit of work to get right. That's why stsadm.webconfig was created.

While this custom stsadm command does not make creating the xpath needed to define the modification any easier, it does make managing your config entries extremely easier. Developers can now define web.config entries in an XML file deployed to the [12]/Config directory, run this stsadm command, and have those entries applied to the web.config file.

For example, there is a sample config file deployed with this command which will configure a web application for version 3.5 of ajax.asp.net [12]/Config/config.sample.ajax35.xml.
  • To apply: stsadm -o webconfig_apply -url http://webappurl -configfile config.sample.ajax35.xml
  • To remove: stsadm -o webconfig_remove -url http://webappurl -configfile config.sample.ajax35.xml

Another thing which can now be accomplished is that farm-specifc config values can be defined in a single solution by creating different xml config files like customapp.dev.xml, customapp.test.xml, customapp.prod.xml. If using WSPBuilder, for example, a developer can add those files to the wsp project in the /12/Config directory, and when the WSP is created and moved through the environments, the config settings will move with the solution.

One thing to point out: it's best to have a special sharepoint web application in development to test your web config changes. It is easy to mess up your web config file, and you don't want to ruin your environment. Start with a single simple config modification, test it, retract it, and then add the next one. Don't start developing your config changes and then test all of them at once.

The config file follows a simple pattern:
<ConfigEntries owner="[Title of config changes. example: ProdConfigChanges]">
<!--
<ConfigEntry>
<Name></Name>
<Path></Path>
<Value><![CDATA[***entry goes here***]]></Value>
<ModType>EnsureChildNode</ModType>
</ConfigEntry>
-->
</ConfigEntries>

example config file (from config.sample.ajax35.xml)
<ConfigEntries owner="AjaxifyMoss35">
<ConfigEntry>
<Name>add[@verb='GET,HEAD'][@path='ScriptResource.axd'][@validate='false'][@type='System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35']</Name>
<Path>configuration/system.web/httpHandlers</Path>
<Value><![CDATA[<add verb='GET,HEAD' path='ScriptResource.axd' validate='false' type='System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35'/>]]></Value>
<ModType>EnsureChildNode</ModType>
</ConfigEntry>
<ConfigEntry>
<Name>add[@name='ScriptModule'][@type='System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35']</Name>
<Path>configuration/system.web/httpModules</Path>
<Value><![CDATA[<add name='ScriptModule' type='System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35'/>]]></Value>
<ModType>EnsureChildNode</ModType>
</ConfigEntry>
<ConfigEntry>
<Name>SafeControl[@Assembly='System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35'][@Namespace='System.Web.UI'][@TypeName='*'][@Safe='True']</Name>
<Path>configuration/SharePoint/SafeControls</Path>
<Value><![CDATA[<SafeControl Assembly='System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35' Namespace='System.Web.UI' TypeName='*' Safe='True' />]]></Value>
<ModType>EnsureChildNode</ModType>
</ConfigEntry>
</ConfigEntries>

Last edited Jul 6, 2009 at 3:33 PM by richfinn, version 9