Directives





Directives

Throughout this chapter we have used the @Page directive to control the default language, code-behind class, and implicit assembly compilation of our .aspx files. In addition to the @Page directive, several other directives are available for use in .aspx files, as shown in Figure. Because every .aspx file is compiled into a class, it is important to have control over that compilation, just as you would via compiler switches if you were compiling a class yourself. These directives give you control over many options that affect the compilation and running of your page.

.aspx File Directives

Directive Name

Attributes

Description

@Page

See Figure

Top-level page directive

@Import

Namespace

Imports a namespace to a page (similar to the Imports keyword in VB.NET)

@Assembly

Name

Src

Links an assembly to the current page when it is compiled (using src implicitly compiles the file into an assembly first)

@OutputCache

Duration

Location

VaryByCustom

VaryByHeader

VaryByParam

VaryByControl

Controls output caching for a page (see Chapter 9 for more details)

@Register

Tagprefix

Namespace

Assembly

Src

Tagname

Registers a control for use within a page (see Chapter 8 for more details)

@Implements

Interface

Adds the specified interface to the list of implemented interfaces for this page

@Reference

PageControl

Specifies a page or user control that this page should dynamically compile and link to at runtime

The @Assembly directive provides a way for .aspx files to reference assemblies that are deployed in the global assembly cache or, using the src attribute, to reference a source file that is compiled and referenced implicitly when the page is referenced. The @Import directive serves the same purpose as the Imports keyword in VB.NET, which is to implicitly reference types within a specified namespace. The @Implements directive gives you the ability to implement an additional interface in your Page-derived class, and the @Reference directive provides a mechanism for referencing the generated assemblies of other pages or user controls.

To see an example of when you might use some of these directives, suppose we decide to deploy the TempConverter class in the global assembly cache so that all the applications on our machine can access its functionality. We also wrap it in a namespace to ensure that there is no clash with other components in our system, and sign it with a public/private key pair. Listing 1-14 shows the source file for our TempConverter component.

-14 Source File for TempConverter Component
' File: TempConverter.vb

Imports System
Imports System.Reflection

<assembly : AssemblyKeyFile("pubpriv.snk")>
<assembly : AssemblyVersion("1.0.0.0")>

Namespace EssentialAspDotNet.Architecture

Public Class TempConverter

  Shared Public Function FahrenheitToCentigrade(val As Double) As Double
    Return ((val-32)/9)*5
  End Function

  Shared Public Function CentigradeToFahrenheit(val As Double) As Double
    Return (val*9)/5+32
  End Function

End Class

End Namespace

To reference the TempConverter in one of our pages, we need to reference the TempConverter assembly deployed in the GAC, and we need to fully scope the reference to the class with the proper namespace. To reference a GAC-deployed assembly, we use the @Assembly directive, and to implicitly reference the namespace in which the TempConverter class is defined, we use the @Import directive. A sample page using these directives to work with the TempConverter component is shown in Listing 1-15. Note that to successfully reference a GAC-deployed assembly, you must use the full four-part name of the assembly, including the short name, the version, the culture, and the public key token.

-15 Sample .aspx Page Using the TempConverter Component
<!-- File: TempConverter.aspx -->
<%@ Page Language='VB' %>
<%@ Assembly Name="TempConverter, Version=1.0.0.0, Culture=Neutral,
graphics/ccc.gifPublicKeyToken=a3494cd4f38077bf" %>
<%@ Import Namespace="EssentialAspDotNet.Architecture" %>

<html>
<body>
<h2>32 degrees Fahrenheit is
 <%= TempConverter.FahrenheitToCentigrade(32)%>
  degrees centigrade</h2>
</body>
</html>

The @Page directive has by far the most attributes of any of the directives. Some of these attributes have been brought forward from similar directives in traditional ASP pages, while many are new and unique to ASP.NET. Figure shows the various @Page directive attributes available, along with their possible values and a description of the attribute usage. The underlined value is the default that will be used if the attribute is left off the @Page directive.

@Page Directive Attributes

Attribute

Values

Description

AspCompat

true | false

Causes this page to run on an STA thread for backward compatibility

AutoEventWireup

true | false

Determines whether events will be auto-wired up (see Chapter 2)

Buffer

true | false

Enables HTTP response buffering

ClassName

Any name

Specifies the name of the class to be generated by this file

ClientTarget

User agent or alias

Specifies the target user agent to use when accessing this page

CodePage

Code page value

Code page value for the response

CompilerOptions

String of compiler options

Compiler options to be added to the compilation command when the page is compiled

ContentType

Any HTTP type string

MIME type of response for this page

Culture

Culture name

Culture to be used when rendering this page

Debug

true | false

Whether this page is compiled with debug symbols

Description

Any text

Not used

EnableSessionState

true | false

Whether session state is used on this page (see Chapter 10)

EnableViewState

true | false

Whether view state is enabled for this page (see Chapter 2)

EnableViewStateMac

true | false

Whether ASP.NET computes a Message Authentication Code (MAC) on the page's view state (to prevent tampering)

ErrorPage

Valid URL

Target URL redirection for unhandled exceptions (see Chapter 5)

Explicit

true | false

For VB.NET, whether explicit declaration of variables is mandated

Inherits

Class name

Code-behind class from which this page will inherit

Language

Any .NET language

Default source language of this page

LCID

Locale ID

Locale ID to use for this page

ResponseEncoding

ASCIIEncoding

UnicodeEncoding

UTF7Encoding

UTF8Encoding

R

esponse encoding for the content of this page

Src

Source file name

Source file name of the code-behind class to be dynamically compiled when the page is compiled

SmartNavigation

true | false

Enables smart navigation feature for IE 5 and higher (saves scroll position without flicker)

Strict

true | false

For VB.NET, whether option strict mode is enabled

Trace

true | false

Whether tracing is enabled for this page

TraceMode

SortByTime

SortByCategory

When tracing is enabled, how the messages are displayed

Transaction

Disabled

NotSupported

Supported

Required

RequiresNew

Whether and how this page participates in a transaction

UICulture

Any valid UI culture

UI culture setting for this page

WarningLevel

0–4

Warning level at which compilation for this page is aborted

One of the attributes that may be of particular interest to developers migrating existing ASP applications is the AspCompat attribute. This attribute changes the way a page interacts with COM objects. If you are using COM objects that were written in the single-threaded apartment (STA) model (all VB COM objects fall into this category), there will be additional overhead in invoking methods on that object because ASP.NET pages will by default run in the multithreaded apartment (MTA) when accessing COM objects. If you find that you are writing a page that has a significant number of method calls to STA-based COM objects, you should consider setting the AspCompat attribute to true to improve the efficiency of communication with those objects. Be aware that enabling this attribute also creates COM wrappers on top of the Request and Response objects enabled with ObjectContext, adding some overhead to interacting with these classes.

The ClassName attribute lets you decide the name of your Page-derived class, instead of accepting the default name, which is derived from the .aspx file name. With the CompilerOptions attribute you can specify any additional compiler switches you would like to include when your page is compiled. For example, Listing 1-16 shows a page that has requested that warnings be treated as errors when this page is compiled and that the page be compiled with overflow checking enabled for arithmetic operations.

-16 Specifying Additional Compiler Options for a Page
<%@ Page Language='VB'
    CompilerOptions="/warnaserror+ /checked+" %>

     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows