Easily Create an ASP.Net User Control Library

This has been a topic that’s been on my mind for a while now. There are a few ways to accomplish this and I think I’ve just found the one that I like the most. The first method is to use the Publish Web-Site method and use the generated assemblies. The problem is, they always have filenames like App_Web.MyControl.ascx..xSrejWsl.dll or something to that effect. Not something named very friendly and really not something you would want to hand off to a customer. The second option, it to compile like the above and then use the Microsoft utility ILMerge to merge all of the assemblies into one. This option I don’t mind, but it will require some custom build events that either look through the output directories and merge all compiled binaries or you’ll manually updated the build script when new assemblies are added. This works, and it’s Ok, but it seemed like a lot of overhead to do something that I feel should be easy anyway. So, today I found a third option that’s been available since Visual Studio 2005 but I just happened to stumble across today. Enter the Web Deployment Project addon:

• Web Deployment Project for Visual Studio 2008
• Web Deployment Project for Visual Studio 2010

Install whichever of the above is appropriate, then follow these steps:

1. Create a new Web Site project.
2. Remove Default.aspx or any default pages that the IDE adds in (VS2010 adds some extra stuff in that I never need, I’d prefer them have just been extra templates, that’s another story though).
3. Add a new user control item to the web site, for the sake of these instructions call it EmailLink.ascx. Add a single literal the page. Notice the “ClassName” property in the Page directives. This is important, it is how you will be able to specify what Namespace your control will be put (which is key if you need everything to be organized like I do). The contents of my ASCX page look like this (you can see in this that I’ve put my class in the Iuf.Web.UI namespace):

<%@ Control Language="VB" AutoEventWireup="false" CodeFile="EmailLink.ascx.vb" ClassName="Iuf.Web.UI.EmailLink" Inherits="EmailLink" %>
<asp:Literal ID="litDisplay" runat="server"></asp:Literal>

5. Now, let’s go to the code behind and add some basic properties and update methods (note, I’m just throwing this together, we would want to include the tags so the toolbox has information on this control if this were production). Here’s the code I added:

Partial Class EmailLink
    Inherits System.Web.UI.UserControl
    Private Sub UpdateLink()
        litDisplay.Text = String.Format("<a href=""mailto:{0}"">{1}</a>", Me.Href, Me.DisplayText)
    End Sub
    Private _displayText As String = ""
    Public Property DisplayText() As String
        Get
            Return _displayText
        End Get
        Set(ByVal value As String)
            _displayText = value
            Me.UpdateLink()
        End Set
    End Property
    Private _href As String = ""
    Public Property Href() As String
        Get
            Return _href
        End Get
        Set(ByVal value As String)
            _href = value
            Me.UpdateLink()
        End Set
    End Property
End Class

7. Now that we’ve added that, this is where the magic happens. Right click on your web site in the solution explorer and choose “Web Deployment Project”. This will add a web deployment file into your site. Double click on it to pull up it’s dialog.
8. Choose “Merge All Pages and Controls into a single Assembly” on the Output Assemblies properties page.
9. On the Compilation properties page, uncheck “Allow this pre-compiled site to be updateable”. Since we’re doing this to offer a reusable library we don’t want these pages to be updatable and we also don’t want to have to distribute them, we just want to distribute the single .DLL that is compiled.
10. To build this library, instead of using the web-sites “Build”, you’ll want to right click on the Web Deployment file in your site and choose build on it. This will create the .DLL in the deployment directory you’ve specified.
11. Now, to use this .DLL, create a new web-site and create/copy this file into the BIN directory of that web-site. To register the control for use on your page you’ll put the following tag at the top of your ASPX page (I named my assembly ControlLibrary):
12. <%@ Register Assembly="ControlLibrary" Namespace="Iuf.Web.UI" TagPrefix="iuf" %>
13. Now, to use the tag, you would use it just like any other User Control, something like this:
14. <iuf:EmailLink ID="test" Href="mailto:nobody@nowhere.com" DisplayText="Email Somebody" runat="server" />