Creating User Controls in Microsoft SharePoint Master Pages

If you find the need to extend SharePoint by including a Web User Control then you are in the right place. I scoured the web looking for a good tutorial for creating User Controls for SharePoint and found many of them incomplete and leaving out important pieces of information. In this tutorial I will show you how to create a User Control with Code-Behind and incorporate it in your SharePoint Master Page.

Create a New C# ASP.NET Web Application Project (.NET 2.0 — 3.5)

Delete the Default.aspx, Scripts Folder, and App_Data folder.

Your Solution Explorer should only contain the following:

Right Click on Your Project – Add – New Files…

Add a Web User Control to the project

Expand the User Control and Open it’s Code-Behind .cs file:

In the user controls’ .cs file add this to the top:

using System;
using System.Collections;
using System.Configuration;
using System.Data;
using System.Data.SqlClient;
using System.Web;
using System.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

Program the file as you so wish.

Right Click on the Solution and Choose Properties.

Change the build options to Sign the Assembly.

Choose a New from the drop down

Give your key a name. I choose to disable password protection.

Build the Project

Open the Visual Studio Tools command prompt and run:

SN -k pathto/bin/mycompiled.dll

This will give you the PublicKeyToken

We need slightly modify to the ascx file so that it uses the compiled DLL instead of the .cs Code-Behind. Change the Inherit tag in the ascx file to something like below :

<%@ Control Language="C#" AutoEventWireup="true" Inherits="SomeControlProject.SomeControl, SomeControlProject, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a66181fff4923fe5" %>

Copy the ascx file to your SharePoint server and place it in: TEMPLATE\CONTROLTEMPLATES

To add the control to SharePoint drop the ascx file into controltemplates folder of SharePoint.

Usually : C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES

Next, drag and drop your signed assembly (DLL file) into GAC or C:\WINDOWS\assembly folder.

In order for SharePoint to trust your new user control it is important to create a SafeControl declarion in the web.config file.

<SafeControls>
  <SafeControl Assembly="SomeControlProject, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a66181fff4923fe5" Namespace="SomeControlProject" TypeName="*" Safe="True" />
</SafeControls>

Finally you are ready to add our user control to your SharePoint Master Page. Open your SharePoint site in SharePoint designer and check out the master page.

To register the control add this at the top of the page:

<%@ Register TagPrefix=”uc” src=”~/_controltemplates/SomeControl.ascx” TagName=”MyControlName” %>

Finally add the control anywhere on your page:

<uc:MyControlName id="whateveruwant" runat="server">

Note: If you make changes to the DLL you must change the version number of the assembly. You must also TAP the ASCX files. Add a few spaces to the files and then save them to get teh Date Modified to be different to prevent caching. May need to refresh the GAC cache.