How to: Create Instances of ASP.NET User Controls Programmatically

Article
10/15/2014

Just as you can programmatically create an instance of any server control on an ASP.NET Web page, you can do the same with a user control.

To create an instance of a user control programmatically

In the user control, be sure that the @ Control directive contains a ClassName attribute that assigns a class to the user control.

The following example sets the ClassName attribute to strongly type a user control.
```
<%@ Control className="MyUserControl" %>
```

In the page where you want to work with the user control, create a reference to the user control with the @ Reference directive.

When you create the user control programmatically, the strong type for your user control is available to the ASP.NET Web page only after you have created a reference to it. For example, the following code creates a reference to a user control created in the MyUserControl.ascx file.

<%@ Reference Control="MyUserControl.ascx" %>

Note
You use the @ Reference when you intend to load the control programmatically. You use the @ Register directive when you add a user control to the page declaratively. For details, see How to: Include a User Control in an ASP.NET Web Page.

Create an instance variable for the user control, using the control's class name. The class will be part of the ASP namespace.

For example, if you want to create an instance of the user control declared as class Spinner, you use syntax such as the following:
```
Protected Spinner1 As ASP.Spinner
```
```
Protected ASP.Spinner Spinner1;
```
Create an instance of the user control in code by calling the LoadControl method.

Assign property values as necessary, and then add the control to the ControlCollection collection of a container on the page, such as a PlaceHolder control.

Note
When you add controls to the ControlCollection object using the Add method, they are placed in the collection in the order they are processed. If you want to add a control to a specific position in the collection, use the AddAt method and specify the index location where you want to store the control.

Example

The following example shows an ASP.NET Web page that loads a user control programmatically. The page includes an @ Reference directive to specify the control's file. The LoadControl method reads the file and instantiates it as a control that can be added to the page.

<%@ Page Language="VB" %>
<%@ Reference Control="~\Controls\Spinner.ascx" %>

<script runat="server">
Private Spinner1 As ASP.Spinner
Protected Sub Page_Load(ByVal sender As Object, _
        ByVal e As System.EventArgs)
    Spinner1 = CType(LoadControl("~\Controls\Spinner.ascx"), _
        ASP.Spinner)
    ' Set MaxValue first.
    Spinner1.MaxValue = 20
    Spinner1.MinValue = 10
    PlaceHolder1.Controls.Add(Spinner1)
End Sub

Protected Sub Button1_Click(ByVal sender As Object, _
      ByVal e As System.EventArgs)
    Label1.Text = Spinner1.CurrentNumber.ToString()
End Sub
</script>
<html>
<head id="Head1" runat="server">
  <title>Load User Control Programmatically</title>
</head>
<body>
  <form id="form1" runat="server">
    <div>
      <asp:PlaceHolder runat=server ID="PlaceHolder1" />
      <br />
      <asp:Button ID="Button1" runat="server" 
        Text="Button" 
        OnClick="Button1_Click" />
      <br />
      <br />
      <asp:Label ID="Label1" runat="server" Text=""></asp:Label>
    </div>
  </form>
</body>
</html>

<%@ Page Language="C#" %>
<%@ Reference Control="~/Controls/Spinner.ascx" %>
<script runat="server">
private ASP.Spinner Spinner1;
protected void Page_Load(object sender, EventArgs e)
{
    Spinner1 = (ASP.Spinner)LoadControl("~/Controls/Spinner.ascx");
     // Set MaxValue first.
    Spinner1.MaxValue = 20;
    Spinner1.MinValue = 10;
    PlaceHolder1.Controls.Add(Spinner1);
}

protected void Button1_Click(object sender, EventArgs e)
{
    Label1.Text = Spinner1.CurrentNumber.ToString();
}
</script>

<html>
<head id="Head1" runat="server">
  <title>Load User Control Programmatically</title>
</head>
<body>
  <form id="form1" runat="server">
    <div>
      <asp:PlaceHolder runat=server ID="PlaceHolder1" />
      <br />
      <asp:Button ID="Button1" runat="server" 
        Text="Button" 
        OnClick="Button1_Click" />
      <br />
      <br />
      <asp:Label ID="Label1" runat="server" Text=""></asp:Label>
    </div>
  </form>
</body>
</html>

Share via

How to: Create Instances of ASP.NET User Controls Programmatically

To create an instance of a user control programmatically

Example

See Also

Concepts

Additional resources