Exploring Windows SharePoint Services

What can I do with a Web.Config?

In case you haven’t heard about it yet, Windows SharePoint Services (WSS) allows both teams and individuals to quickly create Web sites that are used for information sharing and collaboration. One of the main benefits of WSS is that it helps to increase the overall organization productivity. WSS is a free add-on component of Windows Server 2003 and out of the box provides team based services and sites that can operate independently or in conjunction with the Microsoft Office System and other desktop programs. Written as an ASP.NET based application, WSS is designed to leverage the .NET Framework and also serves as a platform for application development. WSS is a complex application that offers many different areas of customization for developers. In this article, we will cover the area of how WSS uses the web.config file and how this can be extended by .NET developers.

A default installation of Windows Server 2003 contains the .NET Framework 1.1. This installation contains a default system wide configuration file called the machine.config. This is an XML based configuration file that is located in the C:WINDOWSMicrosoft.NETFrameworkv1.1.4322CONFIG directory. This file provides the system wide .NET Framework configuration that affects memory usage, server processing and a variety of parameters that control and help to define server processing.

ASP.NET Default Configurations

The machine.config file is a system wide configuration file. In addition to this file, the .NET Framework provides another XML based configuration file called the web.config. The main difference between the machine.config and the web.config is that the web.config can appear in any directory of an ASP.NET application. The settings provided within each of the individual level application configuration files is used to provide a more granular application level control for inheriting and then overriding the machine.config settings. Web.config files are defined in a hierarchical structure. For example, a web.config file deployed in the inetpubwwwrootmyapplication becomes the default configuration file for any ASP.NET application deployed in that directory. If another ASP.NET application is deployed at inetpubwwwrootmyapplicationsubapplication, the web.config file placed in this directory may override the settings defined in the directory above it.

Any changes made to the content of a web.config file are immediately reflected in the processing requests to the web server. These settings are calculated only once and then cached across all subsequent calls. ASP.NET automatically monitors for any file changes that automatically invalidate the existing cache and then forces a re-read of the configuration file.

Each web.config file contains a hierarchy of XML tags and subtags with attributes that specify their configuration settings. As with any XML file, it is case sensitive and must be well formed. Each of the tag names and attributes are camel cased. This means that the first character of a tag is in lower case and the first letter of any subsequent concatenated word is uppercase. The specific attribute values are Pascal case, which means that the first character is uppercase and the first letter of any subsequent concatenated word is also uppercased.

Note: The exception is true and false, which are always lower case.

All configuration information resides between the <configuration> root XML tags. Configuration information between these tags is grouped into two main areas - the configuration section handler declaration area and the configuration settings area. The configuration section handler declarations appear at the top of the configuration file in the <configSections> tags. Each declaration contained in a <section> tag specifies a set of configuration data and the name of a .NET Framework class that provides configuration data in that section.

The configuration section settings follow the <configSections> area and contain the actual configuration settings. There is one configuration section for each declaration defined in the <configSections> area. Each specific configuration section contains subtags with attributes that contain the settings for that section.

The following Web.config file example declares two configuration <section> handlers. One manages application settings and the other manages session state.

<configuration>

<configSections>

<section name="appSettings"

type="System.Configuration.NameValueFileSectionHandler,

System, Version=1.0.3300.0,

Culture=neutral, PublicKeyToken=c88a5c561934e089"/>

<section name="sessionState"

type="System.Web.SessionState.SessionStateSectionHandler,

System.Web, Version=1.0.3300.0, Culture=neutral,

PublicKeyToken=b03f5f7f11d50a3a"

allowDefinition="MachineToApplication"/>

</configSections>

<appSettings>

<add key="dsn" value="localhost;uid=MyUserName;pwd=;"/>

<add key="msmqserver" value="server\myqueue"/>

</appSettings>

<sessionState cookieless="true" timeout="10"/>

</configuration>

A configuration section only needs to be declared once. It can then be placed in either the machine.config file as a system wide setting or in the web.config as an application specific setting.

Note: Remember from above that the configuration files in subdirectories automatically inherit the configuration handlers declared in parent directories.

Many times configuration settings are nested together under section grouping tags. These top level section tags represent the namespace to which the configuration settings are applied. The ASP.NET configuration infrastructure makes absolutely no assumptions about the type of configuration data the infrastructure supports. Configuration section handlers process all web.config data. This enables developers to use the pre-defined tags or create their own specific handlers to process custom defined data. For example, database connection tags are often added to web.config using the <appSettings> tag as shown below.

<appSettings>

<!--GLOBAL Connection string-->

<add key="constring" value="Data Source=(local);Initial Catalog=sweets;Integrated Security=SSPI" />

</appSettings>

Locating the WSS Configuration Files

Like any ASP.NET application, WSS leverages the web.config file extensively. By default, WSS uses the web.config as a way of controlling specific application configuration requirements. For example, if you do a file search on a server running WSS, there are several different web.config files that are returned. It is important to understand what each does before trying to configure them.

Anytime an IIS virtual server is extended with WSS, a top level web.config file is placed in the content root folder. This file defines the configuration settings for the server. For example, these include the HTTP handling for Web parts. A second web.config file is used for Web Part resources that and is placed in the wpresources folder located in the same default content root folder. The web.config file that is found in the wpresource folder should not be modified as this can cause problems with the installation and functioning of the WSS instance. The settings defined within this file are defined to disallow pages and other items that can be compiled. Any modification to this file can cause the security state for the compiled code to be different from code that runs from the inetpubwwwroot directory and result in a fatal security error.

There are a variety of common customizations that can be done to the web.config files for WSS. These include adding custom configuration settings for server extensions, modifying configuration settings so that an ASP.NET application can coexist with WSS and registering a Web Part as a safe control within WSS.

Note: It is important to keep a backup copy of any changes that you make to your web.config files. It is possible that these changes may be lost through service packs or patches.

Adding Custom Configuration Setting

The 60Config folder contains both *.config and *.xml files that are merged together to create a default web.config file for new WSS virtual servers. During the creation of the virtual server, WSS searches this folder for any files with the name of webconfig*.xml and then merges any files found to the contents of the web.config. One this is complete the resulting file web.config is written to the root path of the virtual server. One of the major advantages of using an .xml file in this context to supplement the default configuration settings of the virtual servers is that the customizations are not lost when WSS is upgraded or web.config files are overwritten.

For example, when saved as webconfig.appname.xml in the 60CONFIG directory, the following example adds a safe control and replaces the default run time filter in the web.config.

<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 actions specified above are applied to the configuration settings when a virtual server is extended using WSS. It is important to remember that if there are multiple .xml files the order in which they are assembled and applied is not guaranteed.

Another common customization is modifying the configuration settings for an ASP.NET application to coexist with WSS. This can be done through the following steps.

1. Exclude the path of the application from Windows SharePoint Services

1. Within the Virtual Server Settings page in SharePoint Central Administration select Define Managed Paths.

2. In the Add a New Path section type the URL to exclude and then select the Excluded Path box

2. Clear out the ASP.NET handler used in Windows SharePoint Services and specify the default ASP.NET handler for all pages by opening the web.config file of the application and adding lines as follows:

<httpHandlers>

<clear />

<add verb="*" path="*.aspx" type="System.Web.UI.PageHandlerFactory, System.Web, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />

</httpHandlers>

3. Because Windows SharePoint Services maintains a restrictive trust policy, you may need to adjust the trust level by adding a line like the following to the web.config file of the application.

<trust level="Full" originUrl="" />.

4. You may need to enable the session module by adding the following lines to the web.config file of the application. In the top-level web.config file for Windows SharePoint Services, the default value for the enableSesstionState attribute is false.

<httpModules>

<add name="Session" type="System.Web.SessionState.SessionStateModule"/>

</httpModules>

Note: Once completed if you receive a WSS error that says the Session module is already in the application and can’t be reloaded, simply remove the httpModules section.

Summary

Windows SharePoint Services is a fairly extensive ASP.NET based application that is offered as an add-on product for Windows Server 2003. It is designed to provide an out of the box collaboration platform for enterprises and an extensible application development platform. WSS offers a wide variety of customization and extensibility options that leverage the .NET Framework. It is important to understand the many different options that are available when extending WSS. This article presented one of the options available. This article covered a small portion of the possible customization aspects.