@ Control

Defines attributes that are specific to user controls (.ascx files) that are used by the ASP.NET page parser and compiler. This directive can be used only with (whose source code is contained in .ascx files). For more information about user controls, see ASP.NET User Controls.

<%@ Control attribute="value" [attribute="value" ... ] %>

Attributes

  • AutoEventWireup
    Indicates whether the control's events are autowired. true if event autowiring is enabled; otherwise, false. The default is true. For more information, see ASP.NET Web Server Control Event Model.

  • ClassName
    A string that specifies the class name for the control that will be dynamically compiled when the control is requested. This value can be any valid class name and can include the full namespace of a class (a fully qualified class name). If a value for this attribute is not specified, the class name for the compiled control is based on the control's file name.

    Another page or control can reference the class name assigned to the control by using the @ Reference directive.

  • ClientIDMode
    Specifies the algorithm to use to generate ClientID values for controls. The default value for a page is AutoID.

    The default value for controls is Inherit. Therefore, the default algorithm for controls in a user control is determined by the ClientID setting of the user control. A different default value can be set at the page level in the @ Page directive or in the pages element of the Web.config file. For more information about the algorithms, see ClientIDMode.

  • CodeBehind
    Specifies the name of the compiled file that contains the class associated with the control. This attribute is not used at run time.

    Note

    This attribute is included for compatibility with previous versions of ASP.NET, to implement the code-behind feature. In ASP.NET version 2.0, you should instead use the CodeFile attribute to specify the name of the source file, along with the Inherits attribute to specify the fully qualified name of the class.

  • CodeFile
    Specifies a path to the referenced code-behind file for the control. This attribute is used together with the Inherits attribute to associate a code-behind source file with a user control. The attribute is valid only for compiled controls.

  • CodeFileBaseClass
    Specifies a path to a base class for a control and its associated code-behind class. This attribute is optional, but when it is used the CodeFile attribute must also be present. Use this attribute when you want to implement a shared scenario, where you define common fields (and optionally, associated events) in a base class to reference the controls declared in a user control. Because of the ASP.NET code generation model, if you defined the fields in a base class without using the this attribute, at compile time new member definitions would be generated for the controls declared in the user control (within a separate partial class stub), and your desired scenario would not work. But if you use the CodeFileBaseClass attribute to associate the base class with the user control, and you make your partial class (its name is assigned to the Inherits attribute and its source file is referenced by the CodeFile attribute) inherit from the base class, then the fields in the base class will be able to reference the controls in the user control after code generation.

  • CompilationMode
    Sets whether the control should be compiled, using a string that specifies one of several enumerated options. The default value is Always, so .aspx controls are compiled by default. For details, see the CompilationMode enumeration.

  • CompilerOptions
    A string containing compiler options used to compile the control. In C# and Visual Basic, this is a sequence of compiler command-line switches. For more information about compiler options, see C# Compiler Options or Visual Basic Command-Line Compiler.

  • Debug
    Indicates whether the control should be compiled with debug symbols. true if the control should be compiled with debug symbols; otherwise, false. Because this setting affects performance, you should only set the attribute to true during development.

  • Description
    Provides a text description of the control. This value is ignored by the ASP.NET parser.

  • EnableTheming
    Indicates whether themes are used on the control. true if themes are used; otherwise, false. The default is true.

  • EnableViewState
    Indicates whether view state is maintained across control requests. true if view state is maintained; otherwise, false. The default is true.

  • Explicit
    Determines whether the control is compiled using the Visual Basic Option Explicit mode. true indicates that the Visual Basic explicit compile option is enabled and that all variables must be declared using a Dim, Private, Public, or ReDim statement; otherwise, false. The default is false.

    Note

    This attribute is ignored by languages other than Visual Basic. Also, this option is set to true in the Machine.config configuration file. For more information, see Configuration Files and ASP.NET Configuration Files.

  • Inherits
    Defines a code-behind class for the control to inherit. This can be any class derived from the UserControl class. Used with the CodeFile attribute, which contains the path to the source file for the code-behind class. For more information about code-behind classes, see ASP.NET Web Page Code Model.

  • Language
    Specifies the language used when compiling all inline rendering (<% %> and <%= %>) and code declaration blocks within the control. Values can represent any .NET Framework-supported language, including Visual Basic, C#, or JScript. Only one language can be used and specified per control.

  • LinePragmas
    Determines whether the runtime should generate line pragmas in the source code. These are compiler options that are often used by debugging tools to mark specific locations in a source file. true if line pragmas should be generated; otherwise, false.

  • Src
    Specifies a path to a source file containing code that is linked to the control. In the linked source file, you can choose to include programming logic for your control either in a class or in code declaration blocks.

    You can use the Src attribute to link build providers to the control. For more information, see the BuildProvider class. Also, in versions of ASP.NET prior to 2.0, the Src attribute was used as an alternative way to link a code-behind file to a control. In ASP.NET version 2.0, the preferred approach to linking a code-behind source file to a control is to use the Inherits attribute to specify a class, along with the CodeFile attribute to specify the path to the source file for the class.

  • Strict
    Indicates that the control should be compiled using the Visual Basic Option Strict mode. true if Option Strict is enabled; otherwise, false. The default is false.

    Note

    This attribute is ignored by languages other than Visual Basic.

  • TargetSchema
    Specifies the name of a schema that validates content on the control. This serves only a descriptive purpose; no actual validation is performed, and the attribute is ignored by the parser.

  • WarningLevel
    Indicates the compiler warning level at which you want the compiler to treat warnings as errors, thus aborting compilation of the control. Possible warning levels are 0 through 4. For more information, see the WarningLevel property.

Remarks

This directive can be used only in user controls. User controls are defined in files with the .ascx extension. You can include only one @ Control directive per .ascx file. Further, you can define only one Language attribute per @ Control directive, because only one language can be used per control.

Note

The @ Control directive has a number of attributes in common with other directives that apply to an entire source file, such as the @ Page directive (used in .aspx files for Web pages) and the @ Master directive (used in .master files for master pages).

To define multiple attributes for the @ Control directive, separate each attribute/value pair with a single space. For a specific attribute, do not include a space on either side of the equal sign (=) that connects the attribute with its value. For an example, see the Example section of this topic.

Example

The following code example instructs the ASP.NET page compiler to use Visual Basic as the inline code language and disables saving view state across HTTP requests using the EnableViewState attribute.

<%@ Control Language="VB" EnableViewState="false" %>

See Also

Reference

Text Template Directive Syntax

@ Page

Other Resources

ASP.NET Page Syntax

ASP.NET User Controls