Attributes of the Page Object

for RuBoard

In ASP.old, you wrote the majority of your page-rendering code against five objects (Application, Request, Response, Server, and Session). All these objects exist in ASP.NET, although their relative utility is diminished somewhat by the more structured event-driven paradigm provided by ASP.NET.

For example, in ASP.old you typically built applications based on forms that were submitted to the server and handled in script. The script automatically parsed the elements of the form into members of the Request.Form collection. You could then send data back to the browser as a combination of templated HTML and calls to the Write method of the Response object.

In ASP.NET, you don't have to use Request.Form to read the contents of form controls; instead, you can read the properties of those controls directly. This makes programming much easier, eliminating a conceptual hurdle to building sophisticated user interfaces and ensuring that data handled by your application is strongly typed from end to end. You do not need to use Response.Write to send output to the browser, either. Although you may be accustomed to using this quite frequently in ASP.old, you'll almost never see it in ASP.NET.

The following sections describe elements of the Page object in more depth, including the familiar Request, Response, Server, and Session objects, and adding some new functionality provided by the Page object that's unique to ASP.NET.

Page Directives

Page directives are commands, inserted at the top of an ASP.NET page, that represent a mixed bag of settings pertaining to how the page is rendered and processed .

Table 2.1 shows a complete list of ASP.NET page directives.

Table 2.1. ASP.NET Page Directives

Directive	Description
@Page	A mixed bag of settings pertaining to how the page is rendered, buffered, globalized, and so forth.
@Control	Settings specific to how user controls are rendered. This setting is appropriate for user controls only.
@Import	Imports a namespace.
@Implements	Utilizes an externally defined user control, server control, or COM interface.
@Register	Registers a server control tag prefix and namespace for use in the page.
@Assembly	Links an assembly to the page.
@OutputCache	Determines how the page caches output.
@Reference	Links a page or user control to the current page.

You insert a page directive at the top of the page. Listing 2.23 shows an example of a typical @Page directive.

Listing 2.23 Typical @Page Directive

 <%@ Page language="C#" debug="true" trace="true" %> 

This Page directive instructs ASP.NET to interpret code in the page as C#, to activate debugging, and to execute in Trace mode to assist with debugging and performance analysis.

NOTE

The @Page directive is used when you want to change the default settings for a single page in your ASP.NET Web application. However, some of the settings in the @Page directive can also be altered for an entire directory (using the Web.config settings file) or an entire server (using the Machine.config settings file). See Chapter 5, "Configuration and Deployment," for more information on how to use these files to configure your server.

The next few sections give examples and scenarios that demonstrate and describe when you would use the various page directives. (The debugging and tracing features of ASP.NET are covered in Chapter 3, "Debugging ASP.NET Applications.")

Setting Single-Thread Compatibility Using the AspCompat Attribute

COM components built with Visual Basic 6.0 use single-threaded apartment (STA) threading. To use an STA component with ASP.NET, your ASP.NET page must also use single-threaded apartments.

Setting the AspCompat attribute of the @Page directive to true causes your page to execute on a single thread, ensuring compatibility with STA components. It also makes objects contained by the Page such as Request and Response available to any COM objects utilized in script on the page.

This attribute should be used sparingly because it degrades ASP.NET performance. Use it only in cases where you are unable to port the STA object to .NET.

Controlling Event Handlers Using the AutoEventWireup Attribute

The AutoEventWireup attribute of the @Page directive is used to override the default event procedures used to handle Page events. This attribute is set to true by default.

In general, most of the time this will have any bearing only on the name of the procedure used to handle the Page object's Load event. When AutoEventWireup is true, the event procedure is called Page_Load. If AutoEventWireup is false, you have to create a custom event handler to handle the Page object's events.

This feature is used most often with code behind. In order to make the events fire when AutoEventWireup is set to false, define delegates for Page_Init in the constructor of the code-behind class. Define delegates for all events in the Page_Init(). Listing 2.24 shows an example of the scenario.

Listing 2.24 Definition of a Code-Behind Page_Load Event Procedure Without AutoEventWireup

 public MyPage() {   this.Init += new System.EventHandler(this.Page_Init); } private void Page_Init(object Sender, EventArgs e) {   this.Load += new System.EventHandler(this.MyPageLoad); } private void MyPageLoad(object Sender, EventArgs e) {   //Todo: enter your code here } 

You can see that the Page_Init() is explicitly wired to the event Page_Init by the delegate in the constructor. Then the Page_Init() event handler is used to define delegates for other events. This also allows us to associate a subroutine with any name with a specified event.

For more information on how code behind works, see the section "Separating Presentation from Code Using Code Behind" earlier in this chapter.

Deactivating Page Buffering Using the Buffer Attribute

When the Web server is building a page for display in the browser, it can either send the data to the browser a little at a time, or it can store the entire page and send it to the browser in one fell swoop. Sending the data to the browser all at once is called buffering. Buffering a page can yield significant performance improvements because it potentially lowers the number of TCP packets that must be sent to return the page to the user. It can also make for a more positive perceived user experience because a buffered page renders all at once instead of progressively painting as data arrives.

In ASP.NET, buffering is turned on by default. Setting the Buffer attribute in the @Page directive to false turns off buffering.

Denoting the Page's Class Name Using the ClassName Attribute

You use the ClassName attribute to denote the name of the class used by the page when it is compiled. This attribute is commonly set by Visual Studio .NET in conjunction with the code-behind feature.

For more information on how code-behind works, see the section "Separating Presentation from Code Using Code Behind" earlier in this chapter.

Specifying the Target Client Using the ClientTarget Attribute

You can use the ClientTarget attribute to specify the user agent (a.k.a. browser type) for which the server controls in your application should render their content. It makes sense to use this option in a situation where you have a captive audience that has standardized on a particular browser (as in an intranet), and you are using server controls that adapt to browser capabilities.

NOTE

The ASP.NET documentation doesn't explicitly state that setting this value produces a performance gain, but presumably it would because server controls would not have to sniff the browser before rendering themselves .

Every browser is supposed to pass a user agent string identifying the type and version number of the browser each time it makes an HTTP request. You can programmatically retrieve the user agent string reported by the browser by inspecting the value of Page.Request.UserAgent.

Note that some browsers try to trick the Web server into thinking that they're a different kind of browser by passing a bogus user-agent string. For example, by default, Opera 5.0 identifies itself to the browser as Internet Explorer 5.0. This is done to ensure that the browser will work with Web applications that sniff the browser in brain-dead ways (for example, by attempting to detect the brand of the browser instead of its underlying capabilities).

Setting the Language Using the CodePage Attribute

A code page is a set of mappings between text characters and numbers .

One common code page in the United States is UTF-8, also known as Unicode, and described in Internet RFC 2279 (see http://www.ietf.org/rfc/rfc2279.txt if you're really interested).

It's necessary only to specify the CodePage attribute when the page you've authored was written using a different code page than the Web server it's running on. We're hoping you don't do this too often.

Setting Compiler Options Using the CompilerOptions Attribute

You can use the CompilerOptions attribute to pass additional arguments to the compiler when the page is run. To do this, you'll need to have an excellent handle on how compiler switches work, a page that somehow lacks a capability found in a compiler switch, and fortitude.

We racked our brains trying to figure out why you would use this feature, but we couldn't come up with much. The documentation isn't much help, either. Many of the compiler switches are already represented in ASP.NET in various ways, so it's possible that the CompilerOptions is simply a hook that ASP.NET provides for you, enabling you to take advantage of future compiler options that may become available before ASP.NET officially supports them.

Setting the ContentType Attribute

The ContentType attribute maps to an HTTP setting that tells the browser what kind of data to expect as the response to a request. Almost always, the data sent from the Web server will be an HTML page. However, you may want to change this. You can use the ContentType attribute of the Page directive to make this change.

You change the ContentType attribute in situations where your ASP.NET page is designed to send data other than HTML to the browser; one common, real-world situation would be sending XML directly to the browser. To do this, set the content type to "text/xml". If the output of the page contains well- formed XML data (and nothing but XML data), and your browser has the capability to display XML directly (that is, Internet Explorer 5.0 or later), the XML will render directly in the browser.

Specifying International Culture Using the Culture Attribute

You can use the Culture attribute to specify for which culture the content of your Web page is intended. Culture in this context means international dialect and language. For example, the culture attribute "en-US" stands for U.S. English, whereas "en-GB" stands for the kind of English that our good friends in Great Britain speak.

Certain operations in the .NET framework, such as the formatting of strings, are culture dependent. For example, many European cultures use a comma instead of the decimal point used by Americans and other sensible cultures. (Just kidding.)

Activating Debugging Using the Debug Attribute

Setting the Debug attribute to true activates ASP.NET Debug mode, which provides rich debugging information in the browser to remote machines when an error is encountered in an ASP.NET page.

Debugging is covered in Chapter 3.

Setting the Description Attribute

The Description attribute enables you to append a textual description of your choice to your page. This attribute isn't accessible programmatically; it's presumably just a way for you to insert a comment describing the page in the @Page directive.

Setting the EnableSessionState Attribute

Session state refers to the capability of a Web application to store information for individual users as the user navigates from page to page. Session state is turned on by default; you may want to consider setting the EnableSessionState attribute to false ”that deactivates Session state and can increase performance.

See Chapter 4, "State Management and Caching," for a general discussion of how Session state works in ASP.NET.

Activating View State Using the EnableViewState and EnableViewStateMac Attribute

View state is the feature of ASP.NET that causes a control's properties to be retained across round trips to the server. It is discussed more fully in the section "Taking Advantage of Postback and View State," later in this chapter.

View state is enabled in ASP.NET pages by default. Setting the EnableViewState attribute to false enables you to turn View state off. Note that it is also possible to turn View state off on a control-by-control basis, for controls that support it, by setting the control's ViewStateEnabled property to false.

Turning off View state can increase application performance by reducing the amount of data that must be sent to and from the server.

Setting EnableViewStateMac to true enables an additional check to ensure that View state information was not altered between the time it was sent to the browser by the server and the time it was resubmitted to the server (Mac in this context stands for Machine Authentication Check). This is an important security feature that you should employ whenever sensitive data is stored in View state.

Setting the ErrorPage Attribute

The ErrorPage attribute enables you to redirect to a custom error page of your choosing. The value for the attribute can be any URL. This attribute is commonly set in applications where it's likely that the user will enter a bogus value (a long URL, for example, or perhaps a mistyped query string parameter), and you don't want the user to be confronted with a grungy ASP.NET error page.

Inheriting from a Class Using the Inherits Attribute

Each ASP.NET page is treated as a class. You can cause your ASP.NET page to inherit from another class by setting the Inherits attribute.

You typically use the Inherits attribute to take advantage of code-behind functionality. Code-behind functionality is described in more detail in the section "Separating Presentation from Code Using Code Behind" in this chapter.

Setting the Language Attribute

The Language attribute determines the programming language used in the page. By default, you can choose VB, C#, or JScript, although other .NET languages could be used as well. Note that an ASP.NET page can only have one language.

Setting the Locale Identifier Using the LCID Attribute

The locale identifier (LCID) is an integer that corresponds to a national language setting. The idea behind an LCID is to give the client some idea of what national language the application supports. Because the LCID value is a 32-bit number, the value can be quite granular when describing different dialects of the same language. For example, the LCID value 1033 denotes United States English; the value 2057 denotes the flavour of English spoken in the United Kingdom.

By default, ASP.NET uses your Web server's locale (set in operating system configuration) as the locale for each page. Setting this attribute to a different value overrides the locale setting.

Setting the Src Attribute for Code Behind

The code executed by a particular ASP.NET source file can be located in an external file. You use the Src (source) attribute to specify the name of the external file.

You typically use the Src attribute to take advantage of code-behind functionality. Code-behind functionality is described in more detail in the section "Separating Presentation from Code Using Code Behind" in this chapter.

Enabling Internet Explorer Smart Navigation Features

Setting the SmartNavigation attribute to true enables certain usability features specific to Microsoft Internet Explorer 5.0 and later. In particular, Smart Navigation can improve the user experience by preserving the scroll position on the page and is therefore appropriate in situations where your page contains a long form that is posted back repeatedly.

Setting the Trace Attribute to Activate Tracing

Setting the Trace attribute to true activates tracing for the current page. Tracing helps developers debug an ASP.NET application. Your trace code might simply indicate that a particular piece of code executed successfully; trace code can also give you a sense of how control flows as a page executes and how long each operation in the lifetime of a page takes to accomplish.

Tracing is covered in more detail in Chapter 3.

Setting the TraceMode Attribute to Sort Trace Information

The TraceMode attribute determines how trace information is displayed when tracing is turned on. Setting TraceMode to SortByTime displays trace entries from earliest to latest. Setting the attribute to SortByCategory groups trace entries by type.

Tracing is covered in more detail in Chapter 3.

Setting the Transaction Attribute to Support Transactions

You can add support for transactions to your pages by using the Transaction attribute. Transactions are set to Disabled by default; other settings are NotSupported, Supported, Required, and RequiresNew.

Denoting the Culture with the UICulture Attribute

You can give your ASP.NET page the ability to display culture-specific actions by setting the UICulture attribute. The UICulture attribute differs from the Culture attribute (described earlier in this section) in the sense that while Culture has a stand-alone effect on the display of data (such as date formats and decimalization) in the page, UICulture is simply a marker that enables you to denote a culture or language for later use in your localization code. How you provide the culture-appropriate string resource based on the value of UICulture is up to you.

Setting the WarningLevel Attribute

You can force the .NET compiler to treat compiler warnings as errors by setting the WarningLevel attribute of the @Page directive to true.

Five levels of compiler warnings exist, numbered 0 through 4. When the compiler transcends the warning level set by this attribute, compilation fails. The meaning of each warning level is determined by the programming language and compiler you're using; consult the reference specification for your compiler to get more information about the warning levels associated with compiler operations and what triggers compiler warnings.

@Control Directives

You use an @Control directive in place of an @Page directive in a user control (.ASCX) file. User controls are script files that provide programmable user-interface functionality. The @Control directive has many of the same attributes as the @Page directive.

User controls are discussed in Chapter 9, "Building User Controls and Server Controls."

@Import Directives

The @Import directive is used to make classes found in that namespace easier to access. When you import a namespace, you don't have to refer to the full namespace syntax to refer to a class in that namespace; you can, for example, use the name DataSet instead of System.Data.Dataset.

An Import directive looks like this:

 <@ Import namespace="System.Data" %> 

You can have as many Import directives in your page as you want; each namespace reference should have its own Import directive.

Note that you can use classes in any namespace loaded into the Global Assembly Cache (GAC); this includes all .NET framework classes and anything else you've stuck in the GAC.

Implementing External Interfaces with the @Implements Directive

You use the @Implements directive to implement an interface. To understand why this feature exists, remember that every ASP.NET page is really a kind of subclass of the Page object. If you want the object to have access to functionality that requires the implementation of an interface, you must use this directive.

For example, you could use @Implements in user-control development to implement the IPostBackEventHandler interface as a way of raising events associated with postback.

You can't use the @Implements directive in a code-behind class (specify interfaces by using : in the class declaration).

Registering Controls with the @Register Directive

The @Register directive is used to make your ASP.NET page aware of user controls and server controls. It also gives custom ASP.NET controls a programmer-defined namespace, ensuring that the name of one control doesn't conflict with the name of another control.

Custom ASP.NET user interface controls are discussed in Chapter 9.

@Assembly Directives

The @Assembly directive is used to make your ASP.NET page aware of external components. You can use one of two elements with this directive ”Name or Src. Name is the name of a precompiled assembly (without the .DLL extension). Src represents the name of a source code file (such as myclass.cs).

@OutputCache Directives

You can use @OutputCache directives to control how page caching works. Page caching is a feature that can improve performance on ASP.NET pages whose content changes infrequently.

Caching is discussed in more detail in Chapter 4.

Events Raised by the Page Object

The Page object raises a set of events that you can respond to in code.

The events raised by the Page object are standard .NET events, which means they receive a minimum of two arguments: a Sender (a reference to the object that raised the event) and a collection that represents arguments passed to that event (inherited from System.EventArgs). The contents of this collection differ , depending on the event procedure.

Table 2.2 shows a list of events supported by the Page object.

Table 2.2. Events Supported by the Page Object

Event	Description
AbortTransaction	A transaction was aborted.
CommitTransaction	A transaction was completed.
DataBinding	Data binding was completed.
Disposed	The page has been released from memory. This is the last event.
Error	An unhandled exception was thrown on the page.
Init	The page was first loaded. This is the first event raised by the page.
Load	The page is loaded.
PreRender	The page content is about to be displayed.
Unload	The page is about to be unloaded from memory.

As you've seen in the code examples to this point, the most common event handled in the Page object is Load.

for RuBoard