The composition of a user control is very simple and requires a smaller skill set than that required by
custom control developers. User controls preserve the use of ASP.NET mark-up coupled with the code behind model
(although inline code is an option).
One of the great things about user controls is that they allow a quick conversion from something like an
existing ASP.NET page to a user control - and as a result they have many similarities. Some of the similarities
include the use of existing server controls that ASP.NET offers, as well as the event model that you are familiar
with as ASP.NET developers. User controls provide a quick and easy way to introduce modularity into an ASP.NET web
User controls - unlike ASP.NET pages that have the file extension
.aspx - have the extension
.ascx. User controls files cannot be requested via a browser; they can only be used via the
containing ASP.NET page. Web servers like IIS and Cassini prohibit browsing to files with the
Like ASP.NET pages - in the context of a file based web site - compilation of a user control is done upon
So why after this glowing review should we even care about custom control development in ASP.NET? Custom
controls allow us a more atomic control on authoring, as well as the ability to ship our controls as a dynamic
link library (.
dll) which can be pre-compiled as well as integrating nicely with the Visual Studio
If you are building controls specifically for a certain web application, then user controls will probably
be all you need. However, if your desire is to build redistributable controls that integrate well with the Visual
Studio IDE, then custom controls are the best choice.
User Control example
Even if the main purpose of this article is covering custom controls, I would like to start with a
walkthrough about the creation of a simple user control.
In the following example, I have identified a component that will appear many times within my hypothetical
web site. The user control that we will create simply consists of a
GridView and a
SqlDataSource that queries for all the ContactName's and CompanyName's from the Northwind Customers
When creating user controls I like to create a new folder within my web site entitled... yes you guessed
UserControls; and drop all my user controls into that folder. However, this isn't a requirement.
Step 1: Adding a user control to the web site
Adding a user control to your solution is real simple. You just have to right click your solution and
click Add New Item; then from the dialog window click Web User Control and name the control
Figure 1: Adding a Web User Control
Step 2: Adding the ASP.NET controls to MyUserControl.ascx
As mentioned earlier this user control will merely consist of a GridView and a SqlDataSource ASP.NET
Before we go ahead and add our controls to the user control, notice that the
Page directive is
not used for our user control, and that it has been replaced with the
Listing 1: Control directive
As well as the
Control directive also note that our code behind derives from the
System.Web.UI.UserControl class and not from
Listing 2: Deriving from the UserControl class
There is only one similarity between the
System.Web.UI.Page types: they both derive from
Let's go ahead and add the required server controls to our user control.
Listing 3: Adding a GridView and SqlDataSource server control to our user control
Listing 1-1 shows the final version of
Step 3: Adding our user control to a Web Form
There are a few ways in which we can do this. We can either use the
Register directive, or we
can go ahead and register our user control in the
Register directive is really simple and allows all web forms with the appropriate
Register directive to go ahead and use our user control. Setting up the
directive is easy. We need to provide a
Src for the
user control – all of which are attributes of the
Listing 4: Setting up the Register directive
As well as using the
Register directive, as of ASP.NET 2.0, we can go ahead and
register our user control within the
controls element of the
Listing 5: Registering our use control in the web.config
When registering our user control in the
web.config file, all pages within the web site
can now use the user control omitting the
Step 4: Using our simple user control within a Web Form
This is really simple. Either setup the
Register directive on your Web Form or register your
user control within the
web.config as shown in step 3. With that done, you will be able to use your
control as shown in the following listing.
Listing 6: Using our user control within a Web Form
There are a few things to remember about user controls. The first is that you shouldn't include a
form element, which is a
form control with the
attribute. However, you can use a standard
form element. Also, you should not include any HTML
elements that are already contained in the Web Form, like
head and so on. If you
require either, a
MasterPage might be better suited for your needs.
Figure 2: Our simple user control in action
The power of custom controls is staggering. You can create highly complex controls and then bundle them up
and ship them as compiled managed
.dlls. As I mentioned before, custom controls can provide a richer
interface between the developer and the control, via the Visual Studio IDE. This is achieved using attributes
to decorate various parts of a custom controls internals.
When creating a custom control, we derive our control class from one of two base types:
Deriving from the
Control class allows our control to take advantage of the rendering methods
provided by the
Control class, as well as the use of
WebControl class derives from the
Control class. However, if we derive our
custom control from
WebControl, we get free support for many visual aspects of our control, like font
CSS classes, background colour and so on.
Which class should I derive from?
When you are creating a custom control that requires little or no UI, then you should derive from the
Control class. If your control does require the need for extensive UI support, then you should derive
Creating a simple custom control
In this first part of the series we will create a trivial Label-like control that simply allows the user
to define the text of a server control. This control will derive from the Control class.
Step 1: Creating a new Web Control Library project
Right click on your web site solution and click on the Add New Project. From the dialog window, choose the
Web Control Library project template. You can name this project whatever you want.
Figure 3: Creating a new Web Control Library project
Step 2: Deriving from the Control class
Go ahead and add a new class to your Web Control Library called
SimpleLabel, and derive
SimpleLabel from the
Listing 7: Deriving from Control
Step 3: Adding some functionality to our control
In this step we will override the
Render method defined in the Control class, and also add a
Text property to the class so that our user can define the text of our label.
First, we will add the
Text property to our class and store the value in
ViewState so the control can maintain state over post back.
ViewState will be described in detail in the next part of this series.
Listing 8: Text property
Now we will go ahead and override the
Render method of our control.
Listing 9: Overriding the Render method
In the previous listing, we start off by writing an opening
tag, then writing
out the user defined text and then finally closing that opening
Note: We will discuss the control lifecycle in the next part along with rendering.
Listing 10: Our final control
Please go ahead now and build the project.
Step 4: Using the SimpleLabel custom control within an ASP.NET project
You have two choices here: Either install the resulting
.dll into the global assembly cache
GAC) or drop the
.dll into the
bin folder of your web application. We will
do the latter.
Right click on your web site solution and click Add Reference, a dialog window will appear. Click on the
Browse tab and then browse to the resulting
.dll created from the web control library project.
Figure 4: Referencing our web control library project
.dll reference you can either use the
Control directive to register
your custom controls, or you can use the
web.config file to do so. I will use the
web.config to register my control. If you want to use the
Control directive please check
the beginning of this article.
Listing 11: Registering the web control library
With our control library registered we can now go ahead and use it!
Listing 12: Using our control within a Web Form
Figure 5: Our custom control in all of its glory
If you view the source of the resulting
HTML then you will see that
is a child of the
element, which is how we defined our control in the
Hopefully I have introduced you gently to the world of custom control development. In future parts of
this series we will look at the more advanced features of custom control development, and the design
considerations that we must take into account.
Sorry, no bio is available
This author has published 32 articles on DotNetSlackers. View other articles or the complete profile here.
Please login to rate or to leave a comment.