Today and tomorrow I am in Vienna (Austria) and while writing a section on master pages for the book, my attention got (again) diverted to something that is new in WSS v3: the mysterious SharePoint DelegateControl that you find in a lot of places in the master pages (especially the default.master).

What is this DelegateControl all about? Many times I get this question in the classroom and I always was able to provide a decent (I hope) explanation of what this control exactly does in SharePoint. But this evening I took the time to work out a small demo illustrating what you can do with this control. I must thank Mike Ammerlaan for the email he sent me 5 months ago when I for the first time started to investigate this strange control. His explanation was a big help.

So, let me share what this control is all about. You could see the DelegateControl as a mini SmartPart, a generic control that is able to render a user control you want to appear in your pages. To illustrate this, I have here a small basic Web page stored in a document library in SharePoint. On the page I have the following definition of a DelegateControl in the PlaceHolderMain:

Note that the only thing you do here is to tell the DelegateControl to load a control that is identified with an id BelgianHighlight. Question is of course where this definition of this control is done. Features!!! Features are super important in the new WSS v3 and you definitely have to study it very well since (as I always tell people in my sales courses), features are the money makers of SharePoint 2007. I always receive the full attention of everybody at that moment :)

So, create a feature by creating a folder in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES folder. For example one named BelgianHighlights and create a small feature.xml in it with the following content:

Next create the manifest file called control.xml in the same folder and here you define what the control with ID BelgianHighlight is all about:

Nothing special here. You add a Control element with an ID, a sequence (very important – wait a sec for this) and the ControlSrc which is an attribute that points to the ASP.NET user control that will be loaded in the DelegateControl. This user control can of course contain whatever you need to have as functionality. For the sake of simplicity, in my case it simply shows an image of the most famous Belgian person ‘Manneke Pis’. You definitely have to see this guy when you visit Brussels.

Here is the content of the ASCX I am using for the demo:

You copy this ascx and any resources it uses available in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES possibly in a sub folder to differentiate from the other user controls. Install now the feature using stsadm

stsadm.exe –o installfeature –filename BelgianHighlights\feature.xml

Since it is a feature at the level of the Farm it is immediately activated. If you navigate to your page with the DelegateControl in the browser you will see the user control loaded and displaying the image.

All nice. But so what? Well, suppose you have this picture in 1000 pages on your site rendered through the DelegateControl technique. What if you want to make available a new user control, showing other content, maybe other functionality? Pretty easy. Create a new ASCX and drop it also in the ControlTemplates folder. In my example, I am simply using one displaying another picture. But think of it, SharePoint is using the same technique for showing the search box on the pages. You can find the definition of this in the default.master. You might have a lot of these in production. How can you quickly replace this search box with your own custom search box. Well, follow the same technique as what I am doing here for the picture demo. The feature that is used for the definition of the search box is the ContentLightUp feature. Have a look at it and you will see the same approach as my demo above.

A new user control is thus made available by creating a new feature following the same structure as the first one but now setting a sequence number that is lower than the first one (e.g. 90).

After installing the feature you will see that all of the pages that have DelegateControls with BelgianHighlight as the ControlId will now show the second user control.

That is in short the power of the DelegateControl. As said, the SharePoint product team’s version of the SmartPart :)