Turning an .ascx User Control into a Redistributable Custom Control


David Ebbo
Microsoft Corporation

October 2005

Applies to:
   ASP.NET 2.0
   Visual Studio 2005

Summary: With previous versions of ASP.NET, developers had to decide whether to create custom controls or user controls. This article looks at a method for easily creating custom controls from existing user controls (ASCX files). (6 printed pages)


Brief Outline of the Steps
   Step 1: Authoring the User Control
   Step 2: Testing Your User Control
   Step 3: Use the Publish Command to Precompile the Site
   Step 4: Finding the Resulting Custom Control
   Step 5: Using Your New Custom Control
About the author


Since its early days, ASP.NET has always supported two different ways of authoring server controls:

  1. Custom controls: These are controls written from scratch exclusively using code. Essentially, you write a class that 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 (that is, a DLL), which can then be used by any ASP.NET applications, simply by placing the assembly in the "bin" directory of the application (or in the Global Assembly Cache).
  2. User controls: These controls are written using an .ascx file, which looks much like an aspx page. That is, 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.

These two methods 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 worlds by turning an ascx user control into a redistributable custom control, by making use of the new ASP.NET precompilation features.

Brief Outline of the Steps

The basic steps to make this happen are as follows:

  1. Write your user control as you normally would, typically using the Visual Studio designer.
  2. Test it using a simple page before trying to deploy it.
  3. Deploy the application to precompile it.
  4. Grab the user control's assembly produced by the deployment step, and you're essentially done: You have your custom control.
  5. Finally, use your custom control in other apps the same way as you always use custom controls.

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, such as 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 URLs 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).

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), Visual Studio creates it with the a @control directive that looks like this:


This is fine, except for one thing: we want the class to live within a namespace of our choice (instead of "ASP", which is used by default). To do this, we simply modify the ClassName attribute to include the namespace (this is a new feature in 2.0). Here's an example:


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, and so on.

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:


and the user control declaration:


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 (press 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.
  • Deselect "Allow this precompiled site to be updatable". In updatable mode, only the code behind 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.
  • Select "Use fixed naming and single page assemblies". This will guarantee that your user control will be compiled into a single assembly that will have a name based on the ascx file. If you don't check this option, your user control could be compiled together with other pages and user controls (if you had some), and the assembly would receive 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 strongly name the generated assemblies. This allows you to sign the assembly so that it cannot be tampered with. Additionally, it allows you to place the assemblies in the Global Assembly Cache (GAC), which makes it easier to use machine-wide. I will provide more information 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. For example, 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 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, 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 requires it (or in machine.config to make to globally usable).

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:


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.

Declare a tag for the custom control, for example:


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:


<!DOCTYPE html PUBLIC "-//W3C//DTDXHTML1.0Transitional//EN" 

<script runat="server">
protected void Page_Load(objectsender, EventArgse){


Note   Instantiating your custom control dynamically as described 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 that takes a Type 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 (also called partial caching). If you use "new", any OutputCache directive in your ascx will be ignored.


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—including the restrictions discussed in Step 1—there are many scenarios in which it can be useful.

In the future, the ASP.NET team will attempt to simplify this scenario and make it more powerful with some new tools that are in development. 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.


About the author

David Ebbo is a software architect on the ASP.NET team, and has worked on the product since its pre-1.0 days. His areas of expertise include the parser, compilation system, and various parts of the control framework.

© Microsoft Corporation. All rights reserved.