Section 6.6. Directives

6.6. Directives

Directives are used to pass optional settings to the ASP.NET pages and compilers. They typically have the following syntax:

 <%@ directive attribute=value [attribute=value] %> 

The many valid types of directives will be described in detail in the following sections . Each directive can have one or more attribute/value pairs unless otherwise noted. Attribute/value pairs are separated by a space character . These pairs do not have any space characters surrounding the equals sign (=) between the attribute and its value.

Directives are typically located at the top of the appropriate file though that is not a strict requirement . For example, Application directives are at the top of the global.asax file, and Page directives are at the top of the .aspx files.

6.6.1. Application Directive

The Application directive is used to define application-specific attributes . It is typically the first line in the global.asax file, which is described fully in Chapter 18.

Here is a sample Application directive:

 <%@ Application Language="C#" %> 

There are three possible attributes for use in the Application directive, which are outlined in Table 6-7.

Table 6-7. Application directive attributes

Attribute

Description

Inherits

The name of the class to inherit from.

Description

Text description of the application. This is ignored by the parser and compiler.

Language

Identifies the language used in any code blocks. Valid values are " C# ", " VB ", and " JS ". As other languages adopt support for the .NET Framework, this list will be expanded.


6.6.2. Assembly Directive

The Assembly directive links an assembly to the application or page at parse-time . It is analogous to the /reference: command-line switch used by the C# command-line compiler.

The Assembly directive is contained in the global.asax file for application-wide linking, or in a page ( .aspx ) or user control ( .ascx ) file for linking to a specific page or user control. There can be multiple Assembly directives in any file. Each Assembly directive can have multiple attribute/value pairs.

Assemblies located in the bin subdirectory under the application's virtual root are automatically linked to the application and do not need to be included in an Assembly directive.

Two permissible attributes are listed in Table 6-8.

Table 6-8. Assembly directive attributes

Attribute

Description

Name

The name of the assembly to link to the application or page. Does not include a filename extension. Assemblies usually have a .dll extension.

Src

Path to a source file to dynamically compile and link.


For example, the following Assembly directives link to the assembly or assemblies contained in the MyAssembly.dll file, and compile and link to a C# source code file named SomeSource.cs :

 <%@ Assembly Name="MyAssembly" %> <%@ Assembly Src="SomeSource.cs" %> 

This directive is often used in conjunction with the Import directive, described later in this chapter.

6.6.3. Control Directive

The Control directive is used only with user controls and is contained in user control files ( .ascx ). There can only be one Control directive per .ascx file. Here is an example:

 <%@ Control Language="C#" EnableViewState="false" %> 

The Control directive has many possible attributes . Some of the more common attributes appear in Table 6-9.

Table 6-9. Common Control directive attributes

Attribute

Values

Description

AutoEventWireup

true , false

Enables or disables event autowiring. Default is true .

ClassName

Any valid class name

The class name for the page that will be compiled dynamically.

Debug

true , false

Enables or disables compiling with debug symbols. Default is false .

Description

string

Text description of the page, ignored by the parser.

EnableViewState

true , false

Indicates if view state is maintained across page requests . Default is TRue .

Explicit

TRue , false

If language is VB, tells compiler to use Option Explicit mode. Default is false .

Inherits

Class name

Name of code-behind or other class for the page to inherit.

Language

VB , C# , JS

Programming language used for in-line code and script blocks . As other languages adopt support for the .NET Framework this list will be expanded.

Src

Filename

Relative or fully qualified filename containing code-behind class.

Strict

TRue , false

If language is VB, tells compiler to use Option Strict mode. Default is false .


6.6.4. Implements Directive

The Implements directive is used in page ( .aspx ) and user control ( .ascx ) files or associated code-behind files. It specifies an a COM interface that the current page implements . This allows a page or user control to declare the interface's events, methods , and properties.

For example, the following Implements directive allows access to a custom IDataAccess interface contained in a custom ProgrammingASPNET namespace:

 <%@ Implements Interface="ProgrammingASPNET.IDataAccess" %> 

6.6.5. Import Directive

The Import directive imports a namespace into a page, user control, or application, making all the classes and namespaces of the imported namespace available. Imported namespaces can be part of the .NET Framework Class Library or can be custom.

If the Import directive is contained in global.asax, then it will apply to the entire application. If it is in a page ( .aspx ) or user control ( .ascx ) file, then it only applies to that page or user control.

Each Import directive can have only a single namespace attribute. If you need to import multiple namespaces, use multiple Import directives.

The following namespaces are automatically imported into all pages and user controls and do not need to be included in Import directives:

  • System

  • System.Collections

  • System.Collections.Specialized

  • System.Configuration

  • System.IO

  • System.Text

  • System.Text.RegularExpressions

  • System.Web

  • System.Web.Caching

  • System.Web.Security

  • System.Web.SessionState

  • System.Web.UI

  • System.Web.UI.HtmlControls

  • System.Web.UI.WebControls

The following two lines import the System.Drawing namespace from the .NET Base Class Library and a custom namespace:

 <%@ import namespace="System.Drawing" %> <%@ import namespace="ProgrammingASPNET" %> 

6.6.6. Master Directive

Identifies a page file as being a master page. Master pages are covered in Chapter 11.

6.6.7. MasterType Directive

Assigns a class name to the Master property of a page so the page can be strongly typed.

6.6.8. OutputCache Directive

The OutputCache directive controls output caching for a page or user control . Chapter 17 discusses caching and the use of the OutputCache directive.

6.6.9. Page Directive

The Page directive is used to define attributes for the page parser and compiler specific to the page ( .aspx ) file . No more than one Page directive can exist for each page file. Each Page directive can have multiple attributes.

The Page directive has many possible attributes. Some of the more common attributes of the Page directive are listed in Table 6-10.

Table 6-10. Common Page directive attributes

Attribute

Values

Description

AutoEventWireup

true , false

Enables or disables Page events being automatically bound to methods that follow the naming convention Page_ event , e.g. Page_Load . Default is TRue .

Buffer

true , false

Enables or disables HTTP response buffering. Default is true .

ClassName

Any valid class name

The class name for the page that will be compiled dynamically.

ClientTarget

Any valid user-agent value or alias

Targets user agent that server controls should render content for.

CodeFile

Filename

Used by VS2005 to indicate the name of the code-behind file.

Debug

true , false

Enables or disables compiling with debug symbols. Default is false .

Description

string

Text description of the page; ignored by the parser.

EnableSessionState

true , false , ReadOnly

Enables, disables, or makes SessionState read-only. Default is true .

EnableViewState

true , false

Enables or disables maintenance of view state across page requests. Default is true .

ErrorPage

Any valid URL

Targets URL for redirection if an unhandled page exception occurs.

Inherits

Class name

Name of code-behind or other class.

Language

VB , C# , JS

Programming language used for in-line code.

SmartNavigation

true , false

Indicates support for smart navigation by the browser, which enables scroll position on a page to survive postbacks. Default is false .

Src

Filename

Relative or fully qualified filename containing code behind class.

Trace

TRue , false

Enables or disables tracing. Default is false .

TraceMode

SortByTime , SortByCategory

Indicates how trace messages are to be displayed. Default is SortByTime .

Transaction

NotSupported , Supported , Required , RequiresNew

Indicates if transactions supported on this page. Default is NotSupported .

ValidateRequest

true , false

If TRue (the default) all input data is validated against a hard-coded list of potentially dangerous values, to reduce the risk of cross-site scripting and SQL injection attacks.


The following code snippet is a sample Page directive

 <%@ Page Language="C#" AutoEventWireup="true" CodeFile="Default.aspx.cs"    Inherits="_Default" Trace="true"%> 

6.6.10. Reference Directive

The Reference directive can be included in a page file ( .aspx ). It indicates that another page or user control should be compiled and linked to the current page, giving you access to the controls on the linked page or user control as part of the ControlCollection object.

There are two permissible attributes: Page and Control . For either, the allowable value is a relative or fully qualified filename. For example:

 <%@ Reference Page="AnotherPage.aspx" %> 

6.6.11. Register Directive

The Register directive is used in custom server controls and user controls to associate aliases with namespaces. Chapter 14 discusses custom server controls and user controls.



Programming ASP. NET
Programming ASP.NET 3.5
ISBN: 0596529562
EAN: 2147483647
Year: 2003
Pages: 173

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net