This documentation is archived and is not being maintained.

Adding User Controls to a Web Forms Page

You can add a Web user control to a Web Forms page in Design view by simply dragging the control from Solution Explorer and dropping it where you want it to appear in the page. The Web Forms Designer automatically adds an @ Register directive and a tag for the control to the page. From that point, the control becomes part of the page and is rendered when the page is processed. Also, the control's public properties, events, and methods are exposed to the page and can be worked with programmatically. You can also add user controls to a page programmatically.

Note   The user control must be in the same project as the Web Forms page.

To add a user control to a Web Forms page

  1. In the Web Forms Designer, open the Web Forms page you want to add the control to, and make sure that the page is in Design View.
  2. Select the user control's file in Solution Explorer, and drag it onto the page.

To add a user control to a Web Forms page in HTML view

  1. In the Web Forms Designer, open the Web Forms page you want to add the control to, and then switch to HTML view.
  2. At the top of the page, before the <HTML> tag, add a directive that registers the control so it will be recognized when the page is processed. You use the directive to associate a name and a namespace with the Web user control by specifying TagPrefix, TagName, and Src location values. For example:
    <%@ Register TagPrefix="uc1" TagName="menu" Src="menu.ascx" %>

    Put the directive in its own line. If there are no other directives, make it the first line in the file.

    The values for each attribute are listed in the following table.

    TagPrefixThe TagPrefix determines a unique namespace for the user control, so that if multiple user controls on the page happen to have the same name, they can be differentiated from each other. This will be the prefix to the control's name (such as <myNameSpace:xxx>) in the tag.
    TagNameThe TagName is the name for the user control. This name is used in conjunction with the tag prefix to uniquely identify the namespace for your control, as in the following prefix:tagname element:
    <myNameSpace:myUserControl ... />
    SrcThe Src attribute is the virtual path to the user control, for example "UserControl1.ascx" or "/MyApp/Include/UserControl1.ascx".
  3. In the <BODY> portion of the file, create a tag for your control where you want the control to appear. Use the TagPrefix and TagName you registered in Step 2. Give your control an ID and set the attribute runat=server, as in the following example:
    <uc1:menu id="Menu1" runat="server"/>
  4. If your control has properties that you can set at design time, optionally set them by declaring their values in the tag:
    <uc1:menu id="Menu1" runat="server" enabled=true />
  5. Proceed with designing the rest of your Web Forms page. You can switch to Design view to work with your page. The user control will be displayed using a glyph to indicate its location in the page, but will not display a WYSIWYG rendering in the designer. To edit the control, switch back to HTML view.

Working with User Controls Programmatically

The public properties, methods, and events of a user control that is registered in a page are exposed to the parent Web Forms page. By simply adding a declaration for the user control to the code-behind class for the Web Forms page, you can work with the complete object model of the user control to your page's code.

To set a property of a user control in a Web Forms page

  1. Select the user control file in Solution Explorer and drag it onto your page. Note the ID of the user control displayed in the page.
  2. Press F7 to switch from Design view to the code-behind file.
  3. In the Declarations area, add a line to declare the user control. For example, for a user control of type WebUserControl1 whose ID is myControl1:
    ' Visual Basic
    Public Class MyPage
       Inherits System.Web.UI.Page
       Protected Menu1 As menu
    // C#
    public class MyPage : System.Web.UI.Page
       protected menu Menu1;
    Note   The ID in the code-behind declaration must exactly match the ID for the user control in Design view.

    Now that you have a code declaration for the user control, all of the public properties, methods, and events of your user control are available, and will appear in the IntelliSense statement completion dropdowns.

  4. Write code to call methods or set properties of your user control. For example:
    ' Visual Basic    
    Menu1.Visible = True
    // C#
    Menu1.Visible = true;

For more information, see Developing ASP.NET Server Controls and ASP.NET Server Control Event Model.

Adding User Controls to a Web Forms Page Programmatically

To add Web user controls to a Web Forms page, you must perform some steps that you do not normally need when adding existing Web Forms server controls. For details, see Creating Instances of User Controls Programmatically.

See Also

Introduction to Web User Controls | Creating Web User Controls | Introduction to Web Custom Controls | Recommendations for Web User Controls vs. Web Custom Controls | Adding Controls to a Web Forms Page Programmatically | Walkthrough: Creating a Web User Control