I am writing this post because of the headache I faced trying to load and run a custom user control in SharePoint and the lack of good documentation on how to address the issues I faced. Hopefully this post will help others who are having the exact same problem easily come to some resolution.
WSS 3.0 and Microsoft Office SharePoint 2007 (MOSS) gives one the ability to develop and use custom user controls in SharePoint. Creating a basic custom web user controls is relatively easy and can be done in Visual Studio or notepad if you will. The control is given an extension, “.ascx” and can be loaded into an aspx page and run. In a later post, I will show you have to develop and run a simple custom control in a .Net web environment but in this post I want to talk about an issue I had trying to load and run my user control in a SharePoint page.
After I had created my simple ‘do nothing’ user control, I wanted to make sure that I was able to reference this control and load it into my .aspx page. Once I knew I had the correct references paths and the user control loaded successfully, I could then go in and develop the control. However, two issues arose from this attempt. The first problem was figuring out the path to the user control, the second was enabling permissions to allow the user control to actually run on the SharePoint page.
With regards to the first problem, simply loading the control took a bit time more than I had anticipated since I was not too familiar with the correct paths to use in SharePoint. When you reference your user control in an aspx page, you would use the following code for each user control you load
Of course you will have the code that will load the user control into a placeholder control or panel control or used by another control… To find out how to do so, please read my posting on using custom controls in aspx pages.
The tricky part here is where do you place your user control, then what is the path to insert to point the Src attribute to the user control? What I figured out is that you really want to place your user controls in the CONTROLTEMPLATES folder where you’ll find a number of other SharePoint/WSS 3.0 web controls. This complete path is as follows
c:\program files\Common Files\Microsoft shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES
As long as this control is in the CONTROLTEMPLATES folder, all you will need in the Register directive’s Src attribute is to point the path to the “/_controls/MyUserControl.ascx”. Your register directive will now look like this
You will know the path is correct because either your ‘do nothing’ control will load successfully and your page will be blank, or you will get an error to the effect that the control you are trying to run does not have permission to run, or you may just get a HTTP 403 Forbidden error.
This brings me to the second issue that I found. I found that SharePoint will not just simply run any user control you drop in there. After working with the web.config file (someone had mistakenly pointed me to the file), I finally figured out that being that MOSS/WSS 3.0 runs on Windows Server 2003 (or up coming Windows Server 2008), I had to go and actually set permissions on the file itself to allow itself to be run by SharePoint/.Net.
What you will do in this case is right click on the file to bring up the properties popup menu and under security, you will need to give the local WSS_WPG group account permissions to modify the user control. While you are at it, you may also consider giving the local WSS_ADMIN_WPG group account the same permissions.
After you have completed the above steps, you should find that your user control will load and run successfully… well in this case, it does nothing, but since you don’t get an error, then you know you have been able to load your custom user control.
The only thing I would add is that you should be able create a folder in the CONTROLTEMPLATES folder where you can store all your user controls and part of that will require that you make some minor edit to the web.config file. I will update this post shortly to include details on how you can do that.