SharePoint Delegate Controls Unclouded


Over the past few months I have been working on branding the SharePoint portal of one of the largest international companies. This was really interesting especially that this was the first branding experience for me. While I was looking at the OOB master page ( default.master ), I noticed there is a control called “delegate control” in the head element right below the “PlaceHolderAdditionalPageHead”. After googling and investigating, I can say that Delegate Control is one of the most important features of SharePoint 2007 when it comes to branding and customization.


Back to 2003, When Microsoft released Microsoft SharePoint portal server 2003, it was cool but what extremely annoyed the developers then is the non-extensibility of the product and the difficulty of customization. Now, MOSS 2007 offers many extension points to alter sites even after they have been provisioned. The introduction of SharePoint features has opened up an entire world to modifying master pages, page layouts and the pages themselves. Further, SharePoint introduced Delegate Controls that allow for more granular control over parts of the page.

Why are they cool and handy ?

On every SharePoint deployment I have ever participated in, it has been requested that the Search Box be modified. In previous SharePoint versions, this involved either unghosting and customization and/or creating a whole new site definition. NOW, Thanks to Delegate Controls, you can take any control and place them on a SharePoint page such that they substitute the existing control at whatever scope you desire and yet require no extra coding or redeployment of the pages themselves. They work hand-in-hand with the newly introduced Features Framework to dynamically load a control at runtime based on a key value and sequence number

Enough Theory, How do they work ?

The default.master file that the global site definition deploys contains some Delegate Controls with the following Id values :

  • AdditionalPageHead
  • GlobalSiteLink0
  • SmallSearchInputBox
  • PublishingConsole

For instance, SmallSearchBox displays a search area and the DelegateControl Definition in default.master is :

<SharePoint:DelegateControl runat=”server” ControlId=” SmallSearchBox”>

All versions of SharePoint contain a feature called ContentLightUp that includes a Control element that specifies a control for the DelegateControl with the SmallSearchArea ControlId value. The element looks like this :

<Control Id=”SmallSearchInputBox” Sequence=”100” ControlSrc=”~/_controltempaltes/searcharea.ascx” />

The enterprise version of MOSS contains a feature named OSearchEnhancedFeature that substitutes the searcharea.ascx user control with SearchBoxEx web control that sends the user to the more advanced search page in MOSS.

<Control Id=”SmallSearchInputBox” Sequence=”50″ ControlClass=”Microsoft.SharePoint.Portal.WebControls.SearchBoxEx” ControlAssembly=”Microsoft.SharePoint.Portal, Version=, Culture=neutral,PublicKeyToken=71e9bce111e9429c”>

When SharePoint selects the control to replace the delegate control, it looks through the list of activated controls and selects the best control and the best control is defined as the one that has the lowest sequence number. Because the control element in OSearchEnhancedFeature has a lower sequence number, the control it defines is loaded instead of the one determined in ContentLightup and this occurs without modifying default.master .

There are other DelegateControls, like AdditionalPageHead, that do not have visual elements but instead provide the ability to insert additional HTML at runtime.

For example, I once created a web control called SearchEngineOptimizer that emited META tags ( Meta Tags are html tags that appear in the head of html pages) for search engine optimization and created a feature to load that web control!

Well, there is a couple of tips and recommendations that I want to highlight :

  • By using a feature scoped at web, you can use different search boxes for different areas in your site collection with no extra code.
  • You can load user or server controls, if you are specifying a user control, use URL attribute, if you want to load a server control use ControlClass and ControlAssembly attributes.
  • By adding AllowMultiple=true in to the delegate control declaration, you can make it load more than one user/server controls. ( for instance AdditionalPageHead delegate control is set to allow multiple controls by default).
  • When designing your page, create delegate controls for functionality that might change over time.
  • Keep tack of the sequence and don’t use too low numbers. You don’t want to have trouble overriding the feature in the future.


Delegate Controls are important design options for creating solutions that can mixed and matched with other options. The ability to light up functionality for one site and not another can be a very important tool in the SharePoint developer’s toolbox.

User Controls in SharePoint

SharePoint makes extensive use of User Controls, They are located in the 12 hive in Template\ControlTemplates.
Examples : Welcome.ascx , Toolbar.ascx,…
The deafult web.config includes the content of this folder and its subfolders in the SafeControls section.

So any user control you manually create and place it in the 12 hive in Template\ControlTemplates is automatically considered safe by the safe-mode parser.

Some Notes on SharePoint Architecture

Before reading this post please read the previous two articles ( ISAPI extensions and ISAPI filters ).
I thought of writing my notes in the form of a bulleted list because this is not a detailed article.

  • ASP.NET 2.0 is an ISAPI extension that provides managed alternatives to ISAPI extensions ( HTTPHandler ) and ISAPI filters ( HTTPModule ).
  • SharePoint 3.0 is based on ASP.NET 2.0 which is very extensible ( has extension points that support virtual paths and extensions to parsing )
  • SPVirtualPath Provider extends ASP.NET’s VirtualPathProvider and checks the content DB to know if a user customized (unghosted) the page.
  • SPPageParserFilter extends ASP.NET’s PageParserFilter and is used to prevent the pages from containing undesirable elements ( decided whether the pages can contain code, controls that are allowed, maximum number of controls permited on a page,..)

What are ISAPI Filters ?

An ISAPI filter is a DLL that runs on an IIS server to filter data traveling to and from the server to enhance the functionality provided .
They filter every request until they find one they need to process. Filters can be programmed to examine and modify both incoming and outgoing streams of data. Internally programmed and externally configured priorities determine in which order filters are called.
Filters are implemented as DLL files ( can only be developed using unmanaged C/C++. ) and can be registered on an IIS server on a site level or a global level (i.e., they apply to all sites on an IIS server).

Filters are initialised when the worker process is started and listens to all requests to the site on which it is installed until they fine one they need to process.

Common tasks performed by ISAPI filters include:

  • Changing request data (URLs or headers) sent by the client
  • Controlling which physical file gets mapped to the URL
  • Controlling the user name and password used with anonymous or basic authentication
  • Modifying or analyzing a request after authentication is complete
  • Modifying a response going back to the client
  • Running custom processing on “access denied” responses
  • Running processing when a request is complete
  • Run processing when a connection with the client is closed
  • Performing special logging or traffic analysis.
  • Performing custom authentication.
  • Handling encryption and compression.

Sources : MSDN and Wikipedia

What are ISAPI Extenions?

ISAPI consists of two components: Extensions and Filters. In the last post we briefly discussed the laster. Now I’d like to shed some light on ISAP Extensions.

Most of the modern web sites do more than just deliver static HTML. When a site requires dynamic content, an application is needed to handle the requests, process them and respond.
ISAPI Extensions are true applications that run on IIS. They act as the engine for which the actual server side code is written. Clients can access ISAPI extensions in the same way they access a static HTML page. Certain file extensions can be mapped to be handled by an ISAPI extension ( Just like file associations in Windows , ex. Doc files are associated with WinWord.Exe).

Common ISAPI applications implemented as ISAPI extensions:

  • ASP.dll extension processes traditional ASP Pages
  • aspnet_isapi.dll extension processes ASP.NET Pages.

A Site Collection Is A Boundary

Talking about the difference between a site collection ( SPSite ) and a site ( SPWeb ) , the Site Collection is the unit of authorization for all sites ( SPWebs ) it contains .
I usually see it as a boundary for both security and querying information. In SharePoint we can query information and aggreagate them from different sites ( SPWebs ) but this is limited to the boundaries of a site collection.
In this respect you can think of the query visibility as analogous to aggregating data from two different databases using an SQL Query. In case of Databases, there should be an intermediate step to achieve that and get the correct result set and the same is true for our beloved SharePoint LOL.

SharePoint and Managed Paths

Having a solid understanding of Managed Paths is a definite must for any SharePoint administrator.

A managed path is defined as the path in the URL that is managed by SharePoint. As an example, sites is the managed path in http://MyServer/sites/Ayman. Managed paths cannot be limited for use by specific security groups, nor can they be targeted directly with audiences. They are simply a way to organize a large quantity of site collections.
There are 2 types of managed paths (Explicit and Wildcard). Explicit managed paths allow you to create a single site collection at that specific path only. Wildcard managed paths allow you to create multiple site collections using that managed path.

Here are some examples…

Explicit Managed Path: Accounting
Wildcard Managed Path: Departments

Site Collection URL created using the explicit managed path: http://company/accounting
Site Collection URL’s created using the wildcard managed path: http://company/departments/accounting,http://company/departments/hrhttp://company/departments/it

As you can see the “departments” wildcard path acts as a placeholder to create site collections related to “departments”. The reason why i say it represents a phyiscal hierarchy is because if this were a normal web site there would be a physical folder structure on the hard drive somewhere and departments would be that folder. What managed paths allow you to do is represent that physical structure in the URL for the end users and allow for organization on the administrators part. Plus everything in sharepoint is stored in a database, so there are no physical heirarchies. Managed paths allow you to create that feel.

Now, Can you create a site collection under another one ?
Try to answer