Manipulating User Control Properties

Article
10/17/2014

Once you have created a user control and specified properties on that control, you can change those property values both declaratively and programmatically from the page that contains the user control. You can also use these techniques when adding user controls to other user controls, which is called nesting.

Security Note Avoid storing sensitive information such as user names and passwords as properties of a user control.

To manipulate user control property values declaratively

Declare the user control property name and a value as an attribute/value pair in the user control tag. In the following example, Color and Text are properties of a user control instance created by the Acme:Login custom server control tag. Color is set to blue and Text is set to This is a sample.
```
<Acme:Login Color="blue" Text="This is a sample." Runat="server" />
```

To manipulate user control property values programmatically

Create a user control with properties and an ASP.NET server control or HTML element to display the property values. The following example uses a <span> element to display the Color and Text property values.

<script runat="server">
    Public Color As String = "blue"
    Public Text As String = "This is a simple message user control!"  
</script>

<span id="Message" style="color:<%=Color%>"><%=Text%></span>
[C#]
<script language="C#" runat="server">
    public String Color = "blue";
    public String Text = "This is a simple message user control!";
</script>

<span id="Message" style="color:<%=Color%>"><%=Text%></span>

Register the user control in its containing page or user control with an @ Register directive, defining the tagname and tagprefix of the user control, as well as the path to the user control file. For information about how to include a user control in a page or in another user control programmatically, see Creating Instances of User Controls Programmatically.
In the page's code-declaration block, create code that manipulates the user control's properties.

In the body of the containing page or user control, include any other ASP.NET server controls that you want to participate in manipulating the user control properties. For example, you could include a DropDownList Web server control or an HtmlSelect server control to select colors from to manipulate a Color property.

The following example demonstrates a page that manipulates the user control introduced in step 1.

<%@ Register TagPrefix="Acme" TagName="Message"    Src="simpleusercontrol.ascx" %>

<html>

    <script language="VB" runat="server">
        Sub SubmitBtn_Click(sender As Object, E As EventArgs)
            MyMessage.Text = "Message text changed!"
            MyMessage.Color = "red"
        End Sub 'SubmitBtn_Click
    </script>
    <body style="font: 10pt verdana">
        <h3>A Simple User Control w/ Properties</h3>
        <form runat="server">
            <Acme:Message id="MyMessage" Text="This is a custom message!" Color="blue" runat="server"/>
            <p>
            <asp:button text="Change Properties" OnClick="SubmitBtn_Click" runat=server/>

        </form>
    </body>
</html>
[C#]
<%@ Register TagPrefix="Acme" TagName="Message"    Src="simpleusercontrol.ascx" %>

<html>

    <script language="C#" runat="server">
            void SubmitBtn_Click(Object sender, EventArgs E) {
                    MyMessage.Text = "Message text changed!";
                    MyMessage.Color = "red";
            }
    </script>

<body style="font: 10pt verdana">
    <h3>A Simple User Control w/ Properties</h3>
    <form runat="server">
        <Acme:Message id="MyMessage" Text="This is a custom message!" Color="blue" runat="server"/>
        <p>
        <asp:button text="Change Properties" OnClick="SubmitBtn_Click" runat=server/>

    </form>
</body>
</html>

While there are many similarities in manipulating user control properties from a declarative page or user control and from a code-behind page or user control class, there are significant differences. In particular, if you create the containing page or user control with a code-behind class, as all rapid application deployment (RAD) designers do, you should create the user control you plan to use with a code-behind class as well. This provides clean delineations between your code files and the files you use to render HTML to the requesting client (.aspx and .ascx files). For more information, seeDeveloping User Controls in a Code-Behind File.

Note The examples in the following procedure are modifications of the examples in the To manipulate user control properties programmatically procedure. The code has been modified to work in code-behind files.

To manipulate user control property values programmatically from a code-behind file

In a code-behind file, create user control code that includes properties that you want to manipulate. The following example is an adaptation of the simple user control from the previous procedure.

Imports System
Imports System.Web.UI
Imports System.Web.UI.HtmlControls

Namespace UserControlTest
    Public Class MyUserControl
        Inherits UserControl
         Public Color As String = "blue"
         Public [Text] As String = "This is a simple message user control!"
    End Class 'MyUserControl
End Namespace 'UserControlTest
[C#]
using System;
using System.Web.UI;
using System.Web.UI.HtmlControls;

namespace UserControlTest {
    public class MyUserControl : UserControl {
        public string Color = "blue";
        public string Text = "This is a simple message user control!";
    }
}

In a separate code-behind file, create the containing page or user control that will manipulate the user control property values. For the purpose of this example, this code is stored in a MyPage file with the appropriate language extension.

Imports System
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports UserControlTest

Namespace PageTest
    Public Class MyPage
        Inherits Page
        Public mybutton As Button
        Public MyMessage As MyUserControl
        Public Placeholder As PlaceHolder

        Sub Page_Load(sender As [Object], e As EventArgs)
            Dim MyMessage As Control = LoadControl("uc.ascx")
            Placeholder.Controls.Add(MyMessage)

            Dim mybutton As New Button()
            mybutton.Text = "Change property values"
            mybutton.OnClick = "SubmitBtn_Click"
            Placeholder.Controls.Add(mybutton)
        End Sub 'Page_Load

        Protected Sub SubmitBtn_Click(sender As [Object], e As EventArgs)
            MyMessage.Text = "Message text changed!"
            MyMessage.Color = "red"
        End Sub 'SubmitBtn_Click
    End Class 'MyPage
End Namespace 'PageTest
[C#]
using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using UserControlTest;

namespace PageTest {
    public class MyPage : Page {
        public Button mybutton;
        public MyUserControl MyMessage;
        public PlaceHolder Placeholder;

        void Page_Load(Object sender, EventArgs e) {
            Control MyMessage = LoadControl("uc.ascx");
            Placeholder.Controls.Add(MyMessage);

            Button mybutton = new Button();
            mybutton.Text = "Change property values";
            mybutton.OnClick = "SubmitBtn_Click";
            Placeholder.Controls.Add(mybutton);
        }

        protected void SubmitBtn_Click(Object sender, EventArgs e) {
            MyMessage.Text = "Message text changed!";
            MyMessage.Color = "red";
        }
    }
}

Compile the user control code-behind file and the containing page's or user control's code-behind file into assemblies. You must be sure that the containing page or user control has access to the user control code that you are working with. You can compile them in the same .dll file, or use the following compiler instructions on the command line when compiling the page or containing user control. In the following example, uc.dll represents the DLL compiled from the user control source file.

Note The following compiler command line instructions assume that you are compiling from the directory where the source files reside. It also assumes that you are compiling to the \bin directory. In this case, the \bin directory is a subdirectory of the directory where the source files reside.
```
vbc /r:.\bin\uc.dll /target:library /out:.\bin\p.dll MyPage.vb
[C#]
csc /r:.\bin\uc.dll /target:library /out:.\bin\p.dll MyPage.cs
```
If you have not already done so, make sure that all DLLs you have created are stored in your application's \bin directory so the classes can automatically be linked to the .aspx or .ascx files associated with them.

Create the appropriate .aspx and .ascx files. Be sure to include a PlaceHolder server control in the .aspx file. This control will contain the dynamically generated user interface (UI) from the controls declared in the page code-behind DLL. Also, include any necessary HTML elements for the page and user control code you have written.

Note In this case, do not use the Src attribute in the @ Control or @ Page directives. Since you inherit both classes from an assembly, simply use the Inherits attribute. In addition, if you develop the page and user control in namespaces, you must include the namespace name in the value for the Inherits attribute.

The following example demonstrates the .ascx file for the user control and the .aspx file for the page from the previous examples.

The .ascx file:

<%@ Control Inherits="UserControlTest.MyUserControl" %>
<span id="Message" style="color:<%=Color%>"><%=Text%></span>

The .aspx file:

<%@ Import Namespace="PageTest" %>
<%@ Page language="VB" Inherits="PageTest.MyPage" %>
<%@ Reference control="uc.ascx" %>

<html>

    <body style="font: 10pt verdana">
        <h3>A Simple User Control w/ Properties</h3>
        <form runat="server">

            <asp:placeholder id="Placeholder" runat="server" />

        </form>
    </body>
</html>
[C#]
<%@ Import Namespace="PageTest" %>
<%@ Page language="C#" Inherits="PageTest.MyPage" %>
<%@ Reference control="uc.ascx" %>

<html>

    <body style="font: 10pt verdana">
        <h3>A Simple User Control w/ Properties</h3>
        <form runat="server">

            <asp:placeholder id="Placeholder" runat="server" />

        </form>
    </body>
</html>

Manipulating User Control Properties

See Also

Additional resources