Loading UserControls in SharePoint web parts


If you want to use UserControls in SharePoint web parts you can use SmartPart (http://www.codeplex.com/smartpart). But you can also build a web part that load a UserControl yourself.


If you want to do it yourself you start out by opening Visual Studio (whether you use 2005 or 2008 doesn't matter). Next you create a new project of the type "ASP.NET Web Application".


Create Web Application


Then you can add a new class to the project and you make sure that it inherits from System.Web.UI.WebControls.WebParts.WebPart.


Web Part Inheritance


Now create an new folder in the project that you call "Usercontrols" and add a Web User Control to it.


Create User Control


Make sure that you adjust the Inheritance of your .ascx file to a fully qualified name.


 Fully Qualified Name


Let's go back to the class you created initially and add the user control to it. You add the user control in the CreateChildControls function.


CreateChildControls function


You can see that the function UserControlVirtualPath is called. This function is used to determine where the user control will be located. Reason for this is that the deployment location of the user control changes when you change the location where the assembly is deployed to.

If you deploy the assembly to the GAC the user control will be stored in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\wpresources folder and will have the fully qualified name used to create sub folders. The user control for my project will be stored in C:\Program Files\Common Files\Microsoft Shared\web server extensions\wpresources\TwitterTimelineWebPart\\TwitterPublicTimeline\UserControls if I deploy the assembly to the GAC.

If I were to deploy the assembly to the bin of the web application the user control is deployed to the C:\Inetpub\wwwroot\wss\VirtualDirectories\moss2007dev\wpresources folder.

The UserControlVirtualPath function finds the location of the user control for you.


UserControlVirtualPath function


You can add all the content you like to the user control now. Nothing special about that.

One thing that we need to take care of that is SharePoint specific is the deployment.

I will do it manually, so everyone can copy this.

You start out be creating a .ddf file that will help you create the package. The .ddf file can be stored in the root folder of your project.  I will call the file SolutionPackage.ddf. More information about creating the ddf file can be found here (http://msdn.microsoft.com/en-us/library/bb466225.aspx).


ddf file


Next you need to create the manifest.xml file that will make sure that all files are deployed correctly. Create a folder "DeploymentFiles" and create a file that you call manifest.xml in it.

In the manifest you will have to create an Assemblies element with a child Assembly element in which you will specify the assembly you want to deploy. The property DeploymentTarget indicates whether the assembly will be deployed to the GAC or to the web application bin. If you want to deploy the assembly to the GAC the DeploymentTarget property needs to be GlobalAssemblyCache. If you would like to deploy to the bin of the web application you would use WebApplication.


The ClassResources element is a child  element of the assembly element and will have a child element ClassResource. You will need to fill in the location of the resource file (the .ascx file) in the package in the FileName property. The Location property is used to indicate the folder that the resource file will be deployed to. In this case we will create a sub folder TwitterPublicTimeline with a sub folder

UserControls to store the user control in.


The Assembly element has another child element called SafeControls. The child element SafeControl is used to create the safecontrol entries in the web.config. You will need to add the information about your assembly in the Assembly, Namespace and TypeName properties. The Safe property should be set to True..that was the whole point right?


manifest file


A great reference that describes the schema of the manifest file is located here (http://msdn.microsoft.com/en-us/library/ms442108.aspx).


After creating the ddf and the manifest files you start a command prompt and go to the folder where your ddf file is stored. You can then type "makecab /f SolutionPackage.ddf".

This will create the wsp package and include the files mentioned in the ddf file, including the manifest file.

If you want to check whether all files are actually in the package you copy the .wsp file and rename it to a .cab file. Then you extract it and check whether all files are in there.


Now you are ready to upload you .wsp file to your SharePoint environment. You can use the stsadm addsolution command for that.


addsolution stsadm command


After that you can go your Central Administration and deploy the solution to your web application. The Solution Management page can be found on the Operations page under the Global Configuration heading.

Click on the solution name and on the Deploy Solution link. Now select the web application you want to deploy the web part to and the time at which you want the deployment to run.


Your web part is now deployed. You will only need to add it to the web part gallery of your site collection be browsing to the site settings page of your site collection and select Web Parts under Galleries. Click New and select the dll of your web part. Scroll back to the top of the page and click the "Populate Gallery" button.

Congratulations! You can now add your web part to a web part page!

Comments -
  1. Gravatar

    Mirjam, this is great.
    Here is excerpt from best pratcices:
    "Using Web Controls
    When you inherit and override controls in the Microsoft.SharePoint.WebControls namespace, remember that SharePoint Web controls are templated controls. Unlike Microsoft ASP.NET Web controls, they are defined and rendered with templates instead of with the CreateChildControls method. Instead of having a thick CreateChildControls method that uses the new operator to create child controls, perform most child control creation and rendering by using the rendering templates that are referenced in the Template, AlternateTemplate, DisplayTemplate, CustomTemplate, and AlternateCustomTemplate properties of the SharePoint Web control. SharePoint Web controls do inherit the CreateChildControls method, but that method should typically do little or nothing beyond calling the parent control's CreateChildControls method and perhaps a bit of "final polish" rendering, such as assigning default values to child control properties in New mode or assigning the current values in Edit mode."

  2. Gravatar

    Hi Shannan,

    The Microsoft.SharePoint.WebPartPages namespace is located in the Microsoft.SharePoint.dll assembly. If you make sure that this assembly is copied to your local machine you can develop there, but you can't test anything. For developing SharePoint solutions you are better of developing on a server with SharePoint installed on it.


  3. Gravatar

    Thanks for the article.

    Is there any benefit to taking your approach rather than using smartpart? Or is this mainly for the purpose of technical understanding?


  4. Gravatar

    Hi LTG,

    One of the main benefits is that you have more control over what is happening in your code. It can also be beneficial if you want to create a web part pane that uses a user control as you will take the same approach for that.
    Part of it is just preference of course.


  5. Gravatar



Leave a Reply


Please add 3 and 7 and type the answer here: