Directives configure the run-time environment that will execute the page. In ASP, only one directive was supported—@Language—and you had to place it on the very first line of the page. The following code shows an ASP directive.
<% @Language="VBScript" CodePage="1232" %>
Several new directives have been added to ASP.NET and, at the same time, their usage has been made easier and dependent on less strict conditions. In ASP.NET, directives can be located anywhere in the page, although is a good and common practice to place them at the beginning of the file. In addition, the name of a directive is case-insensitive and the values of directive attributes don't need to be quoted. All the feasible ASP.NET directives are listed below.
- @ Page. Defines page-specific attributes that guide the behavior of the page compiler and the language parser that will preprocess the page.
- @ Control. Defines control-specific attributes that guide the behavior of the control compiler.
- @ Import. Indicates a namespace to import into a page or user control.
- @ Implements. Indicates that the page, or the user control, implements a specified .NET Framework interface.
- @ Register. Creates a custom tag in the page or the control. The new tag (prefix and name) is associated with the namespace and the code of a user-defined control.
- @ Assembly. Links an assembly to the current page or user control.
- @ OutputCache. Controls the output caching policies of a page or user control.
- @ Reference. Links a page or user control to the current page or user control.
With the exception of @Page and @Control, all directives can be used both within a page and a control declaration. @Page and @Control are mutually exclusive. @Page can only be used in .aspx files, while the @Control directive can only be used in .ascx files. The syntax of a processing directive is unique and common to all supported types of directives. Multiple attributes must be separated with spaces and no spaces must be placed around the equal sign (=) that assigns a value to an attribute.
<%@ Directive attribute="value" [attribute="value"...] %>
Each directive has its own closed set of typed attributes. Assigning a value of the wrong type to an attribute, or using a wrong attribute with a directive, results in a compilation error.
The content of directive attributes is always rendered as plain text. However, attributes are expected to contain values that can be rendered to a particular type. When the ASP.NET is parsed, all the directive attributes are extracted and parked in a dictionary. Names and number of the attributes must match the expected schema for the directive. The string that expresses the value of an attribute is valid as long as it can be converted into the expected type. For example, if the attribute is designed to take a boolean value, then "True or "False are its only feasible values.
The most important, and most frequently used, directive in ASP.NET is @Page. The @Page directive can only be used in .aspx pages and originates a compile error if used with other types of ASP.NET pages such as controls and web services. Each .aspx file is allowed to include at most one @Page directive. Although not strictly necessary from the syntax point of view, the directive is realistically required by all pages of some complexity. @Page features about 30 attributes that can be logically grouped in three categories: compilation, overall page behavior, and page output. Compile-related attributes are Language, Debug, ClassName, Src, and Inherits. The page behavior is affected by attributes such as AutoEventWireup, AspCompat, ErrorPage, Transaction, EnableSessionState, and EnableViewState. Finally, the output of the page can be controlled through attributes such as ClientTarget, ContentType, Culture, and ResponseEncoding. For more information about the technical aspects of page directives and their attributes, see the ASP.NET documentation available through the MSDN channel and the community sites such as www.gotdotnet.com and www.asp.net.
Dino Esposito is Wintellect's ADO.NET and XML expert, and a trainer and consultant based in Rome, Italy. Dino is a contributing editor to Windows Developer Magazine and MSDN Magazine, and the author of several books for Microsoft Press including Building Web Solutions with ASP.NET and ADO.NET and Applied XML Programming for .NET. Contact Dino at [email protected].
