Corey Roth [MVP]

A common question I get with new SharePoint developers is "How do I deploy my user control in SharePoint?".  Many times they know of the SmartPart or even how to make their own, but its the matter of deploying things that may not be clear.  Before starting this, you need to read how to build and deploy a web part.  Many of the concepts in that article are used here and explained in more detail.

To build a user control, you start in very much the same way as you do with regular ASP.NET.  My recommendation is to start by creating a web application project.  You can also use a regular class library, but its easier if you use a web application project since it has the file types you need as well as references.  If you already have a class library, you can easily convert it to a web application project using a hack.

Once you have a web application project, create your user control as normal.  Build the project and then its time to deploy.  We'll first talk about where the files go on the server and then we'll look at how we can get the files there with a solution package.  Let's assume, I have a control called MyControl.ascx.  This file has to be deployed to the SharePoint server along with its binary.  If you are using a SmartPart, the ascx file to go is in a folder called UserControls located in the root of your web sites folder (by default c:\inetpub\wwwroot\wss\VirtualDirectories\80).  However with true SharePoint development you have to break the my controls go in X folder on my site way of thinking.  In SharePoint, everything is designed to be modular no matter how many web applications your server hosts. 

I recommend creating your own web part to host your user control that will work with any folder.  SharePoint itself puts all user controls in the CONTROLTEMPLATES folder in the 12 hive (C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12).  You can place your controls here as well, but I recommend creating a subfolder here to keep your controls separate.  In this case, I will create a folder called MyControls and copy MyControl.ascx into it.  At this point you are probably wondering what is the path to my control if its in the 12 hive?  On any SharePoint web application, there is a virtual directory called _controltemplates.  This happens to map to the folder we need.  Therefore, the path you would reference in your web part (or any web page) would be ~/_controltemplates/MyControls/MyControl.ascx.

Now, it is just a matter of deploying the binary.  In traditional ASP.NET, you could just copy the DLL of your web application project to the bin folder of the web application.  However, with SharePoint we can't do that without specifying Code Access Security which is a pretty big undertaking when you are starting out.  For any file that is in the bin folder, SharePoint requires a security policy be set specifying exactly what permissions your DLL has.  I recommend deploying to the bin folder, but if you are just starting out, you don't want to go there yet.  To get around this for now, there are two options: 1) Change the TrustLevel in the web.config to Full or 2) Deploy the DLL to the Global Assembly Cache.  I strongly recommend against #1, so for the sake of starting out, just copy your DLL to the GAC.  You will need to strongly name your assembly.  Any time you copy the DLL to the GAC, you will need to either recycle the application pool that your web application is using or reset IIS.  I know that can be a pain, but once you implement CAS, you don't have to do that any more.

Just like with a web part, you have to add your user control as a safe control.  Just specify the assembly name and allowed namespaces.

At this point you are ready to try your new user control out.  To add it to a page like a web part, I recommend you follow the steps in this post to make your own SmartPart.  If you don't know how to deploy a web part, follow my post on how to deploy a web part.  Once you have your smart part added, specify the path I mentioned above (~/_controltemplates/MyControls/MyControl.ascx).  You can also add user controls to your master pages, just like you would in ASP.NET.  Just create the reference and add it to the .master.

This may sound like a lot at this point but it's really not bad.  If there is enough interest in the article, I will try and get some code together in one package so people can use it as a starting point.  That is how you manually deploy a user control, we'll move onto how we do it with a solution package.

Deploying via Solution Package

For deployment, we will pretty much follow what we did in the deployment of the web part.  For more details on building solution packages, please see that post.  In this case a feature is not necessary unless you want to automate the deployment of the user controls onto an existing page.  The cab.ddf file only contains lines to copy the binary and .ascx file.

; ** MyControls.wsp  **
.OPTION EXPLICIT     ; Generate errors 
.Set CabinetNameTemplate=MyControls.wsp     
.set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory
.Set CompressionType=MSZIP;** All files are compressed in cabinet files
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package

Solution\manifest.xml manifest.xml

;binaries
bin\MyControls.dll MyControls.dll

;feature files

;template files
MyControl.ascx CONTROLTEMPLATES\MyControls\MyControl.ascx

The Manfiest.xml file will contain entries to copy your ascx file out as well as copy your binary to the GAC.  It will also add the Safe Control entry that you need.  Here is what the file would look like.  The TemplateFile element is used to specify every .ascx file that you want copied to the server.  More details on what you can do with the manifest file are here.

At this point, you build and deploy the .wsp file as described in my web part post.  Again, I strongly recommend reading that post if you are not familiar with any of the deployment steps yet.  The nice thing about having your user control in a solution package is that it is now completely portable.  It can be deployed to your other SharePoint servers very easily.  Once you have mastered the process, I recommend you start deploying your binaries to the bin folder with Code Access Security.  Once you have the solution package built, adding CAS is pretty easy and it saves you from having to kill your app pool every time you do a deployment.