[Previous] [TOC] [Next]

Visual Studio and Custom Controls

In this section, we'll build a simple control (the default control Visual Studio generates for you) and see how it fits on a Web form. Visual Studio will create a simple control that contains a single Text property, and it will render that Text property to the end browser. It's a good way to discover how server-side controls work.

Create a Custom Control

  1. Begin by opening the ControlORama project from Tutorial 3.

    Graphic
  2. Add a new project to ControlORama. Select File | Add | New Project. Name the new project CustomControlLib. Choose the project type to be a Windows project, and select Web Control Library as the template, like so:

    Graphic

    Visual Studio gives you a simple Web control to start with. Listing 4-2 shows the default code generated by Visual Studio for a Web Control Library.

    Listing 4-2

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Text;
    using System.Web.UI;
    using System.Web.UI.WebControls;
    
    namespace CustomcontrolLib
    {
       [DefaultProperty("Text")]
       [ToolboxData("<{0}:WebCustomControl1
          runat=server></{0}:WebCustomControl1>")]
       public class WebCustomControl1 : WebControl
       {
          private string text;
    
          [Bindable(true)]
          [Category("Appearance")]
          [DefaultValue("")]
          public string text
          {
             get
             {
                return text;
             }
             set
             {
                text = value;
             }
          }
    
          protected override void Render(HtmlTextWriter output)
          {
             output.Write(Text);
          }
       }
    }
    

    The code generated by Visual Studio includes a simple class derived from System.Web.UI.WebControl. WebControl derives from the standard Control class, adding some standard properties along the way. Notice the code has a single property named Text and overrides Control's Render method. This is a real, functioning control (although all it really does is act very much like a label).

  3. Build the project by selecting Build | Build Solution from the main menu.

  4. Add the new control to the toolbox. Switch to the ControlORama project within the Solution Explorer. Highlight the Default.ASPX page and switch to the Design view by selecting the Design tab along the bottom of the code window. Reveal the toolbox by hovering the cursor over the Toolbox tab on the left-hand side of Visual Studio. Then right-click anywhere in the toolbox to open the shortcut menu.

    Graphic
  5. Select Choose Items… from the local menu. Visual Studio will begin searching your computer for various components that it can add to the toolbox (including both .net components and .com components). Then it will show the Choose Toolbox Items dialog box.

    Graphic
  6. Now find the control that Visual Studio just built. Click the Browse button in the Choose Toolbox Items dialog box. Navigate to the ControlORama project directory and then go to the CustomcontrolLib directory. Then open the Bin\Debug directory. (Visual Studio builds debug versions by default.) Select the CustomControlLib.DLL assembly and click the Open button.

    WebCustomControl1 will appear in the Choose Toolbox Items dialog box. The check box will show it as selected.

    Graphic

    As soon as you click the OK button in the Choose Toolbox Items dialog box, the new WebCustomControl1 will appear in the toolbox. To make it easier to find the control, right-click on the toolbox and select Sort Items Alphabetically.

    Graphic
  7. Place the control on a page. To see how the control works, you need to give it a home. Add a new page to the Web site. Select the ControlORama project from the Solution Explorer. Select Web site | Add New Item, and add a Web form. Name the Web form UseCustomControls.aspx.

    To place the control on the page, switch to Design mode. Pick up the WebCustomControl1 from the toolbox and drop it onto the Web form.

    Graphic

    The text showing within the control is the default text shown by a rendered control-basically the control's type. Change the Text property in the control and watch it show up in the designer.

    Graphic

    Take a look at the source code for the control again-specifically looking at the Render method. Notice the method simply uses the output parameter (an HtmlTextWriter) to send the Text property to the browser. That's why the Text property is showing after you change it in the designer.

    Listing 4-3

    <%@ Register Assembly="CustomcontrolLib"
    Namespace="CustomcontrolLib"
    TagPrefix="cc1" %>
    

    Listing 4-3 shows the code Visual Studio added to the ASPX file to accommodate the control. You can see it by selecting the Source tab from the bottom of the code window in Visual Studio. The Register directive tells the ASP.NET runtime where to find the custom control (which assembly) and maps it to a tag prefix. Listing 4-4 shows how the control is declared on the page with the control's Text property set to the string "The control's Text property…".

    Listing 4-4

       <form id="form1" runat="server">
        <div>
            <cc1:webcustomcontrol1 id="WebCustomControl1_1"
            runat="server"
            text="The control's Text property…">
            </cc1:webcustomcontrol1>
            <br />
        </form>
    

    Now take a moment to change a few of the control's properties and see what happens in the designer (for example, changing the font is always very noticeable). The properties you see in the Properties page are all standard, and they show up because the control is derived from System.Web.UI.WebControl.

  8. Now add a text box and a push button to the Web page. After you drop them on the page, Visual Studio adds the code shown in Listing 4-5.

    Listing 4-5

       <form id="form1" runat="server">
        <div>
            <cc1:webcustomcontrol1 id="WebCustomControl1_1"
            runat="server"
            text="The control's Text property…">
            </cc1:webcustomcontrol1>
            <br />
            <br />
            <asp:Label ID="Label1"
            runat="server"
            Text="Type something here;">
            </asp:Label>
            <asp:TextBox ID="TextBox1" runat="server"
            Width="282px">
        </asp:TextBox>
            <br />
            <asp:Button ID="Button1"
            runat="server" OnClick="Button1_Click"
            Text="Set Control Text" />
            </div>
        </form>
    

    Notice the standard ASP.NET controls (the button, the text box, and the label) all begin with the asp: prefix while the new custom control uses the prefix cc1:. Visual Studio made up the tag cc1:, although you could change that by adding a tag prefix attribute to the Control class.

  9. Add an event handler for the push button by double-clicking on the button in the designer. Have the push button pull the text from the TextBox and use it to set the control's Text property.

    protected void Button1_Click(object sender, EventArgs e)
       {
          this.WebCustomControl1_1.Text = this.TextBox1.Text;
       }
    

Now surf to the new page with the control. When you type something into the text box and click the button, the browser sends your request to the server. The browser responds by taking the text from the TextBox and using it to set the Text property of the WebCustomControl1.

Graphic

Notice how the new control appears in the control tree with tracing turned on. (You can turn on page tracing by setting the page's Trace property to true.)

Graphic

You have now built a simple control. The control framework is pretty flexible, and you can send out anything you want using the Render method. Next, we'll develop a more sophisticated control that demonstrates more advanced control rendering.

[Previous] [TOC] [Next]