Using a UserControl

In the previous chapter we created a UserControl, and now we will try using it for the first time. Pick a page in your project, or simply create a new one for the purpose, and open it. The first thing we have to do, is declare our UserControl. It can be done either in each page where it's used, or globally in the web.config file. There is no performance difference, but when declaring UserControls in the web.config file, the controls have to reside in a different directory than the page(s) using it.

For now, let's just declare it within the page. Add the following line below the standard page declaration:

<%@ Register TagPrefix="My" TagName="UserInfoBoxControl" Src="~/UserInfoBoxControl.ascx" %>

Make sure that the src value matches the path to your UserControl file. Now you may use the UserControl in your page, like any other control. For instance, like this:

<My:UserInfoBoxControl runat="server" ID="MyUserInfoBoxControl" />

If you look at the page now, you will see our UserControl in action, although the information will be a bit... limited. We will have to set a value for the properties we defined, for things to get just a bit more interestingly. Fortunately, it's very easy:

<My:UserInfoBoxControl runat="server" ID="MyUserInfoBoxControl" UserName="John Doe" UserAge="45" UserCountry="Australia" />

You see, every public or protected member can be accessed declaretively, allowing easy access to them when we use our control. However, with this specific UserControl, chances are that you will be receiving the information from an external resource, like a database, and then populating the UserControl from there. This usually involves the CodeBehind of the page, so how can we do that? Pretty simple, actually. In the CodeBehind of the page, try something like this:

protected void Page_Load(object sender, EventArgs e)
{
    // These values can come from anywhere, but right now, we just hardcode them
    MyUserInfoBoxControl.UserName = "Jane Doe";
    MyUserInfoBoxControl.UserAge = 33;
    MyUserInfoBoxControl.UserCountry = "Germany";
}

Loading dynamically

Sometimes you may wish to add UserControls to your page dynamically instead of declaring them. It's actually quite simple too. You need an existing control where you can add the UserControl to, for instance a Panel. If there's no logical control on your page to add it to, you may create one for the purpose - the PlaceHolder control is for situations just like that.

On your page, define it like this:

<asp:PlaceHolder runat="server" ID="phUserInfoBox" />

In the CodeBehind of the page, we add the control like this:

phUserInfoBox.Controls.Add(LoadControl("~/UserInfoBoxControl.ascx"));

We use the LoadControl method to instantiate the UserControl by specifying the path. This is very easy, but also very anonymous - because we just use the LoadControl method, we can't really use our own, custom properties. To do that, we need to make .NET aware of it. On the page, add the following declaration in the top:

<%@ Reference Control="~/UserInfoBoxControl.ascx" %>

Now we can access the UserInfoBoxControl class like if it were a regular class, which also means that we can typecast the UserControl returned by the LoadControl method to this type. In the next example, we do just that, then we set the properties, and at last, we add it to the PlaceHolder:

UserInfoBoxControl userInfoBoxControl = (UserInfoBoxControl)LoadControl("~/UserInfoBoxControl.ascx");
userInfoBoxControl.UserName = "John Doe";
userInfoBoxControl.UserAge = 78;
userInfoBoxControl.UserCountry = "Spain";
phUserInfoBox.Controls.Add(userInfoBoxControl);

This will come in handy, for instance when you're adding multiple instances of the same UserControl to a single page, because you can do it inside a loop.