Share via

@ Register

  • Article

Creates an association between a tag prefix and a custom control, which provides developers with a concise way to refer to custom controls in an ASP.NET application file (including Web pages, user controls, and master pages).

<%@ Register tagprefix="tagprefix"
   namespace="namespace"
   assembly="assembly" %>
<%@ Register tagprefix="tagprefix"
   namespace="namespace" %>
<%@ Register tagprefix="tagprefix"
   tagname="tagname"
   src="pathname" %>

Attributes

  • assembly
    The assembly in which the namespace associated with the tagprefix attribute resides.

    Note

    The assembly name cannot include a file extension. Also note that if the assembly attribute is missing, the ASP.NET parser assumes that there is source code in the App_Code folder of the application. If you have source code for a control that you want to register on a page without having to compile it, place the source code in the App_Code folder. ASP.NET dynamically compiles source files in the App_Code folder at run time.

  • namespace
    The namespace of the custom control that is being registered.

  • src
    The location (relative or absolute) of the declarative ASP.NET User Controls file to associate with the tagprefix:tagname pair.

  • tagname
    An arbitrary alias to associate with a class. This attribute is only used for user controls.

  • tagprefix
    An arbitrary alias that provides a shorthand reference to the namespace of the markup being used in the file that contains the directive.

Remarks

Including the @ Register directive in a page or user control allows you to lay out custom server controls or user controls using declarative Custom Server Control Syntax.

Note

You can also register custom controls on all the pages of an application by using the controls Element for pages (ASP.NET Settings Schema) in the Web.config file.

Use the @ Register directive in the following situations:

  • To add a custom server control declaratively to a Web page, a user control, a master page, or a skin file (see ASP.NET Themes and Skins Overview).

  • To add a user control declaratively to a Web page, a user control, a master page, or a skin file.

Note

The tagprefix value "mobile" is used by ASP.NET to identify the mobile Web controls in the System.Web.UI.MobileControls namespace. You should avoid using this prefix for your controls.

When you use the @ Register directive to reference a control, you can place the code for the control in the following places:

  • As source code in the application's App_Code folder, where it will be dynamically compiled at run time. This is a convenient option during development. If you choose this option, you do not use the assembly attribute in the @ Register directive.

  • As a compiled assembly in the application's Bin folder. This is a common option for deployed Web applications.

  • As a compiled and signed assembly in the global assembly cache (GAC). This is a common option if you want to share a compiled control among multiple applications. You can reference a control in the GAC by assigning an identifying string to the assembly attribute. The string specifies the required details about the control, including its fully qualified type name, its version, its public key token, and its culture. The following fictional string illustrates a reference to a custom control in the GAC:

    <%@ Register  tagprefix="custom"
     namespace="Mycompany.namespace"
     assembly="Mycompany.namespace.control, Version=1.2.3.4, 
        PublicKeyToken=12345678abcdefgh, Culture=neutral"  %>

    For more information about referencing assemblies, see add Element for assemblies for compilation (ASP.NET Settings Schema).

For declarative user controls, use the tagname, tagprefix, and src attributes. The first two are always used together as a colon-separated pair (tagprefix:tagname) when you declare the control in the page. You can map multiple namespaces to the same tagname, as in the following example:

<% @Register tagprefix="tag1" namespace="MyNamespace1"/>
<% @Register tagprefix="tag1" namespace="MyNamespace2"/>

The src attribute value can be either a relative or an absolute path to the user control source file from your application's root directory. For ease of use, it is recommended you use a relative path. For example, assume you store all your application's user control files in a \Usercontrol directory that is a subdirectory of your application root. To include the user control found in a Usercontrol1.ascx file, include the following in the @ Register directive:

Src="~\usercontrol\usercontrol1.ascx"

The tilde (~) character represents the root directory of the application.

Note

If your user control is in the same directory as the page that contains it, the src attribute value should be the name and extension of the .ascx file.

When including custom server controls that you have compiled into a .dll file for use with your application, use the tagprefix attribute with the assembly and namespace attributes. If you do not include the namespace attribute, or if you assign an empty string ("") to it, a parser error will occur.

Warning

When you develop a custom server control, you must include it in a namespace. If you do not, it will not be accessible from an ASP.NET page. For more information about developing custom ASP.NET server controls, see Developing Custom ASP.NET Server Controls.

Example

The following code example uses @ Register directives to declare tagprefix and tagname aliases, along with assigning a src attribute, to reference a user control within a Web page. The first part of the code is a simple user control consisting of an ASP.NET Calendar control. The second portion of the code is a page that hosts the control. Note that the tagprefix attribute assigns an arbitrary prefix value to use with the tag. The tagname attribute uses the value of the class name assigned to the user control (although the value of this attribute is arbitrary and any string value can be used--you do not have to use the class name of the control being referenced). The src attribute points to the source file for the user control, relative to the application root folder. The user control is referenced within the body of the page by using the prefix, a colon, and the name of the tag, in this form: <uc1:CalendarUserControl runat="server" />.

<%@ Control ClassName="CalendarUserControl" %>
<asp:calendar id="Calendar1" runat="server" />

<%@ Page %>
<%@ register tagprefix="uc1" 
    tagname="CalendarUserControl" 
    src="~/CalendarUserControl.ascx" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Calendar Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <uc1:calendarusercontrol runat="server" />
  </form>
</body>
</html>

See Also

Concepts

ASP.NET Web Page Syntax Overview

Reference

Directive Syntax

Other Resources

ASP.NET User Controls