This article applies to ASP.NET 2.0 and Visual Studio 2005.
Background
Since its early days, ASP.NET has always supported two different ways of authoring server controls:
- Custom Controls: these are controls written from scratch exclusively using code. Essentially, you write a class which extends Control (directly or indirectly), and you take care of everything. You need to write logic to create child controls that you want to use, and you override the Render method to perform rendering. Typically, you build this control into a redistributable assembly (i.e. a DLL), which can then be used by any ASP.NET applications, simply by placing the assembly in the 'bin' directory of the app (or in the Global Assembly Cache).
- User Controls: these control are written using an ascx file, which looks much like an aspx page. i.e. you can simply drag and drop the UI elements that you want to use into the design surface. You don't need to worry about control creation, nor about overriding the Render method.
Looking at those two methods, they are very different, and each has a number of advantages and disadvantages. I won't discuss them all, but will focus on those that are relevant to this article:
- Custom Controls require a lot of development expertise to be written, while User Controls are authored using an advanced designer, and are much more approachable. For this reason, User Controls typically take a lot less time to write.
- Custom Controls can easily be redistributed without having to give away their sources. On the other hand, User Controls are always used based on an ascx text file, making it less ideal for reuse across applications.
The goal of this article is to show how you can have the best of both world by turning an ascx user control into a redistributable custom control, by making use of ASP.NET 2.0's new precompilation features.
Brief outline of the steps
The basic steps to make this happen are as follows:
- Write your User Control as you normally would, typically using the Visual Studio designer.
- Test it using a simple page before trying to deploy it.
- Deploy the app to precompile it.
- Grab the user control's assembly produced by the deployment step, and you're essentially done: you have your Custom Control.
- Finally, use your Custom Control in other apps the same way as you always use Custom Control's.
We will look at those steps in more detail in the rest of the article.
Step 1: Authoring the User Control
To author the User Control, it is best to start with an empty app that contains nothing other than the ascx. While the authoring of the User Control uses 'standard' techniques, there are some restrictions that you need to be aware of in order for it to be successfully turned into a standalone Custom Control.
The main restriction is that the User Control needs to be self contained. That is, it cannot be dependent on app global things like App_Code or global.asax. The reason for this is that since the goal is to turn the UserControl into a standalone DLL, it would break in other apps if it relied on code that is not part of that DLL.
One exception to this rule is that the UserControl can be dependent on assemblies that live in the bin directory (or in the GAC). You just have to make sure that the other assemblies are always available when you use your Custom Control in other apps.
Another tricky thing is the use of static resources, like images. After you turn it into a Custom Control in a standalone assembly, it becomes hard for it to keep such references, and avoiding them simplifies deployment. If you really must have such references, one option is to use absolute URL's if you can guarantee that the resource will always be available on a certain site. Or you can look into machine wide resources (e.g. src="/MyImages/welcome.jpg"), though you will then need to make sure the resources are installed on the server machine (e.g. as part of some setup).
Ok, so let's start and actually author the User Control. Visual Studio 2005 gives you the choice to place the code in a separate file, or use inline code. This is a matter of personal preference, and either one will work to create a Custom Control. For this article, we will use inline code. When you create the User Control (say MyTestUC.ascx), VS creates it with the a @control directive that looks like this:
<%@ Control Language="C#" ClassName="MyTestUC" %>
This is fine, except for one thing: we want the class to live within a namespace of our choice (instead of 'ASP', which is what's used by default). To do this, we simply modify the ClassName attribute to include the namespace (this is a new feature in 2.0). e.g.
<%@ Control Language="C#" ClassName="Acme.MyTestUC" %>
That's really the only 'special' thing you need to do. Now you can go ahead and implement your User Control as you always would: add some server control, some client HTML, server script, client script, etc...
Step 2: Testing your User Control
Before trying to turn the User Control into a Custom Control, it is a good idea to test it in the source app using a simple page. To do this, simply create a new Page in Visual Studio, go to design View, and drag and drop your User Control into it.
The two notable pieces of your page are the Register directive:
<%@ Register Src="MyTestUC.ascx" TagName="MyTestUC" TagPrefix="uc1" %>
and the User Control declaration:
<uc1:MyTestUC ID="MyTestUC1" runat="server" />
Note that at this point, the Register directive uses the User Control syntax (Src/TagName/TagPrefix) and not the Custom Control syntax (TagPrefix/Namespace/Assembly). This will change after we turn the User Control into a Custom Control.
Run your page (Ctrl-F5) and make sure the User Control works the way you want before moving to the next step.
Step 3: Use the Publish command to precompile the site
The next step is to use the new Publish command to precompile your site and turn your User Control into a potential Custom Control. You'll find the command under Build / Publish Web Site. In the Publish dialog, do the following:
- Pick a Target Location. This is the location on your hard drive that your site will be precompiled to.
- Uncheck 'Allow this precompiled site to be updatable'. In updatable mode, only the code behing file (if any) would get compiled, and the ascx would be left unprocessed. This is useful in some scenarios, but is not what you want here since you want the resulting DLL to be self contained.
- Check 'Use fixed naming and single page assemblies'. This will guarantee that your User Control will be compiled into a single assembly, which will have a name based on the ascx file. If you don't check this, your User Control could be compiled together with other pages and User Controls (if you had some), and the assembly would get a random name that would be more difficult to work with.
Though it is entirely optional, note that the Publish Web Site dialog lets you strong name the generated assemblies. This allows you to sign the assembly so that it cannot be tempered with. Additionally, it allows you to place the assemblies in the Global Assembly Cache (GAC), which makes it easier to use machine wide. More on this in Step 5.
Go ahead and complete the dialog, which will perform the precompilation.
Note: This same step can also be accomplished without using Visual Studio by using the new aspnet_compiler.exe command line tool. The options it supports are basically the same as what you see in the Publish dialog. So if you are more command line inclined, you might prefer that route. e.g. you would invoke it using the command: 'aspnet_compiler -p c:\SourceApp -v myapp -fixednames c:\PrecompiledApp'.
Step 4: finding the resulting Custom Control
Now, using the Windows Explorer or a command line window, let's go to the directory you specified as the target so we can see what was generated. You will see a number of files in there, but let's focus on the one that is relevant to our goal of turning the User Control into a Custom Control.
In the 'bin' directory, you will find a file named something like App_Web_MyTestUC.ascx.cdcab7d2.dll. You are basically done, as this file is your User Control transformed into a Custom Control! The only thing that's left to do is to actually use it.
Note: In case you're curious, the hex number within the file name (here 'cdcab7d2') is a hash code that represents the directory that the original file was in. So all files at the root of your source app will use 'cdcab7d2', while files in other folders will use different numbers. This is used to avoid naming conflicts in case you have files with the same name in different directories (which is very common for default.aspx!).
Step 5: Using your new Custom Control
Now that we have created our Custom Control, let's go ahead and use it in an app! To do this, let's create a new Web application in Visual Studio. We then need to make our Custom Control available to this application:
- In the solution explorer, right click on your application, and choose Add Reference.
- In the Add Reference dialog, choose the Browse tab.
- Navigate to the location of your Custom Control (App_Web_MyTestUC.ascx.cdcab7d2.dll) and select it. It will be copied to the bin directory of your new app.
Note: as an alternative, you can choose to place the assembly in the GAC instead of the 'bin' directory. In order to do this, you need to choose the Strong Name option in Step 3. You then need to add your assembly in the <assemblies> section of web.config in the Web application that wants to use it (or in machine.config to make to globally usable).
Now let's create a test page that uses the Custom Control. This is similar to Step 2, except that you are now dealing with a Custom Control instead of a User Control.
First, add a Register directive to your page. It should look something like this:
<%@ Register TagPrefix="Acme" Namespace="Acme" Assembly="App_Web_mytestuc.ascx.cdcab7d2" %>
Note how we are using a different set of attributes compared to Step 2. Recall that in Step 1, we made sure that the ClassName attribute included a namespace. This is where it becomes useful, as Custom Control registration is namespace based. Also, you need to specify the assembly name, which is why having a name that is easily recognizable is useful, as discussed in Step 3.
Now, let's declare a tag for the Custom Control. e.g.
<Acme:MyTestUC id="MyUC" runat="server" />
That's it, you can now run your app (Ctrl-F5), and you are using your new Custom Control!
This shows how to use your Custom Control declaratively, but note that it can also be used dynamically, just like any other control. To do this, just create the control using 'new'. Here is what the previous sample would look like using dynamic instantiation:
<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
protected void Page_Load(object sender, EventArgs e) {
Label1.Controls.Add(new Acme.MyTestUC());
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
<form id="form1" runat="server">
<div>
<asp:Label ID="Label1" runat="server"></asp:Label></div>
</form>
</body>
</html>
Note: instantiating your Custom Control dynamically as above is basically the equivalent of instantiating your original User Control using the LoadControl API. Note that you can no longer use the standard LoadControl API after converting it to a Custom Control, since Custom Controls don't have a virtual path. However, ASP.NET 2.0 has a new LoadControl override which takes a Type, and that you could use in this case. The one reason I can think of that you might choose to call LoadControl instead of just using 'new' is to take advantage of fragment caching (aka partial caching). If you use 'new', any OutputCache directive in your ascx will be ignored.
Conclusion
This article outlines how to turn a User Control into a Custom Control, in order to take advantage of the strength of each model. While there are some limitations with this hybrid model (see Restrictions in Step 1), there are many scenarios for which it can be useful.
In the future, the ASP.NET team is looking at simplifying this scenario and make it more powerful with some new tools that are in the work. For example, you would be able to take an entire application containing an App_Code directory and multiple User Control, and turn it all into a single assembly that can easily be dropped into the 'bin' directory of other apps. Though it will allow some more powerful scenarios, note that the basic idea behind it is essentially the same as what is shown in this article.