Online training on user controls in ASP.NET
Part one of a five-part series of blogs

User controls are the key to using ASP.NET effectively - this blog explains how and why to create and use user controls, with code examples for VB and C#.

  1. User Controls in ASP.NET (this blog)
  2. How the User Controls will Work for our Case Study
  3. Raising Events for User Controls - Visual Basic
  4. Raising Events from User Controls in C#
  5. Problems with User Controls in ASP.NET

This user controls tutorial is part of a much larger ASP.NET tutorial series of blogs.  Wise Owl also run a full range of ASP.NET training courses.

Posted by Andy Brown on 17 October 2012

You need a minimum screen resolution of about 700 pixels width to see our blogs. This is because they contain diagrams and tables which would not be viewable easily on a mobile phone or small laptop. Please use a larger tablet, notebook or desktop computer, or change your screen resolution settings.

User Controls in ASP.NET

I think there are two keys to writing effective websites in ASP.NET.  The first is to understand data classes; and the second is to use user controls liberally.

There are a couple of things that you can do to make life with user controls easier.  One is to use VB, not C# (although this blog shows both); and the other is to bear in mind the issues that Visual Studio has with user controls, as set out at the end of this blog series (they're not a problem if you know about them).

Simple User Controls

Consider the example I've used throughout this ASP.NET tutorial: creating a searchable to-do list.  Here's what happens when a user does something wrong:

Error message on search form

If you try to add a task without typing in text, you see an error message.


This error message may appear several different places.  You want to make sure it has a consistent look, and is easy to use.  The answer - as so often in ASP.NET - is to put it in a user control.

Creating the User Control

A user control is just part of a page, so one way to create it is to include it as part of a page, then extract the HTML lines of interest and copy them into the user control:

HTML for error

The error will show up in a div tag with a CSS class set.


The main difference between a user control and a page is the file extension (ascx, and not aspx).

Having worked out what your user control will include, start to create it:

Adding a new item to project

Right-click on your project and choose to add a new item to it.


You can now give your user control a name, and choose a language:

Four steps to create a user control

The numbered steps are listed below.

The numbered steps to follow are:

  1. Choose a language (VB or C#).
  2. Choose to create a user control.
  3. Give your user control a name (Wise Owl have a convention that they should all begin wtih uc - I'm not sure how universal this is).
  4. Choose to add it (the master page option is greyed out because a user control can't have a master page).

You will now see something similar to the following (the C# version would look identical):

User control directive

The only difference between this and a page directive is the highlighted word. 

You can now either create the HTML for the user control, or copy it in from a page:

The user control in design view The user control in source view
Design view Source (HTML) view

Two things to note here are:

  1. The styles aren't applied in design view, because at this stage the user control can't know what style sheet the main page will be using.
  2. Don't be afraid to give controls on user controls the same name as those on the containing page.  The two are managed independently. 

Including the User Control on a Page 

By far the easiest way to add a user control to a page is to drag it on in design view:

Dragging user control onto page

Click on the ucError.ascx user control and drag it to the correct position on the page.

This will give you the user control in design view:

User control in design view

The user control appears where you drag it (you can click to edit it separately).


In source view you can see what's happened: 

HTML added for user control to page

The user control is registered at the top of the page, and used within it.

Here are the two lines of interest for our ucError user control.  First the page registers that it will use our user control:

Registering user control

You can change the tag name and tag prefix to any sequence of characters you like.


We then include this user control somewhere on our page:

Using user control

You must use the same tag name/prefix as when you registered the user control.

Giving User Controls Properties

Our achievement so far is underwhelming: all we've done is to get the same error message appearing at the top of every page:

Error user control at top of page

The error message shows up at the top of the page.


As it happens, we've made the div tag in the user control invisible, so you wouldn't even see this!

We need some way to specify how the user control displays, and the easiest way to do this is to give it a property (usually best) or method.  Let's call this property ErrorMessage.  Here's how it will look inside our user control in VB:

Partial Class ucError

Inherits System.Web.UI.UserControl


WriteOnly Property ErrorMessage As String

Set(value As String)


'tells the user control what to display

'(main page should have made it visible)

divError.InnerText = value


End Set

End Property


End Class

Here's the C# equivalent:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;


public partial class ucError : System.Web.UI.UserControl


public string ErrorMessage




// set how error message appears

divError.InnerText = value;




Here we're using a div tag running at the server to display the text; normally I would use an ASP.NET literal web server control to make life easier.  They both do the same thing.

Changing User Controls from a Main Page 

Now that we've given our user control a property, you can set this in either your HTML or in code.  In HTML you would just specify the ErrorMessage property for the control: 

Setting the error message for our user control

The ErrorMessage property will appear in Intellisense when you start to type it in!


Although this looks impressive, you nearly always use code to change user control properties.  Here's how we'd set an error message in VB:

'if error found, show it

ucError1.ErrorMessage = ThisErrorMessage

ucError1.Visible = True 

And here's the C# equivalent:

// if error found, show it

ucError1.ErrorMessage = ThisErrorMessage;

ucError1.Visible = true

When the main page sets the ErrorMessage property of the user control, the user control will change the inner text for its divError tag to display the error!

Hiding the User Control on Page Load 

We have one problem left: we need to make sure that the error message doesn't appear permanently, once set.  To do this, just hide the user control whenever the page loads, whether in VB:

Protected Sub Page_Load(ByVal sender As Object,

ByVal e As System.EventArgs) Handles Me.Load


'hide error messages on every load

ucError1.Visible = False

Or in C#:

protected void Page_Load(object sender, EventArgs e)


// hide error on every load

ucError1.Visible = false;

Although initially the error message will be hidden for every page, subsequent events may display it.

A Footnote - Multiple User Controls and Nested User Controls

It's a common scenario to include multiple versions of a user control on the same page, and to put one user control within another.  Consider a simple toolbar:

Toolbar in ASP.NET

The humble Wise Owl intranet's main toolbar (don't ask what Wes Brown is doing there!).


This comprises a single user control called ucMenu, which itself contains 10 instances of a user control called ucMenuButton.  If you look at the ucMenu control you'd see something like this:

Ten user controls included

The menu user control includes 10 menu buttons.

Of course, you've still got the problem of how to get the menu buttons to tell a webpage that they've been clicked, but I'll cover raising events later in this blog. 

This blog has 0 threads Add post