Using Directives to Modify Web Page Compilation

283 The code in Ex am ple 6- 8 is straightforward. First, a server-side method called cstExpression_ServerValidate is added to the page to handle server-side validation. This method is actually an event handler with a signature thats appropriate for the CustomValidator controls ServerValidate event. Setting the OnServerValidate attribute of the asp:CustomValidator tag wires the handler method to the event. Second, a client-side function, cstExpression_ClientValidate, is added to the page to handle client-side validation. This function is called by the client-side validation code when it is time for the txtExpression field to be validated. Setting the ClientValidateFunction attribute of the asp:CustomValidator tag wires up this function.

6.5 Using Directives to Modify Web Page Compilation

You can modify web page compilation by including directives. Directives are keywords that are recognized and acted on by the ASP.NET page compiler. They affect a pages compilation, rather than its presentation. Directives are delimited by the characters and and can appear at any location in the source file although Microsoft says that standard practice is to place them at the top of the file. For example, the following Page directive was shown in Ex am ple 6- 1 , earlier in this chapter: Page Language=vb AutoEventWireup=false CodeBehind=WebForm1.aspx.vb Inherits=IdeExamples.WebForm1 Directives are similar in form to HTML tags. There is the directive itself, followed by one or more attributes that specify various settings associated with the directive. A directive without attributes has no effect. Directives are different from HTML tags in that the delimiters are different and in that directives have no closing tags. ASP.NET defines the following directives and associated attributes: Assembly Provides a way to reference assemblies defined elsewhere. This directives attributes are: Name Specifies the name of an assembly in the global assembly cache. For example: Assembly Name=System.Windows.Forms SRC Specifies the path of a Visual Basic .NET source file to be compiled and referenced. The path is relative to the web applications virtual folder. For example: Assembly SRC=SomeClass.vb Either the Name or the SRC attribute can be specified, but not both. If multiple assemblies are to be referenced, the Assembly directive should appear multiple times, like this: Assembly Name=System.Windows.Forms Assembly Name=System.Drawing Note the following when using the Assembly directive: • Assemblies located in the applications bin folder are automatically referenced—there is no need to use the Assembly directive. 284 • The Assembly directive cant reference compiled assemblies that arent in the global assembly cache. • Source files referenced with the SRC attribute must be located somewhere underneath the web applications virtual folder. Control Modifies compilation of a user control. User controls are discussed in Sect ion 6.11.1 later in this chapter. This directives attributes are: AutoEventWireup Indicates whether the controls events are autowired to appropriate handlers found within the Control class. Allowed values are true and false . The default is true . This is identical to the same concept found in Page classes. See Sect ion 6.2.1 in Sect ion 6.2 earlier in this chapter. ClassName Specifies a class name for the compiled control. This can be any name that is valid for a Visual Basic .NET class. By default, the name is constructed from the filename of the user control. If the filename is filename.ascx , then the ClassName value is filename_ascx . CodeBehind Is used by Visual Studio .NET projects instead of the Src attribute to specify a code-behind file. CompilerOptions Specifies arbitrary arguments to be passed to the Visual Basic .NET compiler. The format of these arguments is the same as for the Visual Basic .NET command-line compiler. The default is the empty string. Command-line compiler options are not documented in this book. Debug Specifies whether to compile the control in debug mode. Allowed values are true and false . The default is false . Compiling in debug mode enables features such as rich error messages suitable for developers and setting breakpoints. Description Is a place for the developer to describe the control. Neither ASP.NET nor Visual Studio .NET uses it in any way. EnableViewState Specifies whether view state will be maintained across page requests. Allowed values are true and false . The default is true . See Sect ion 6.8 later in this chapter for more information. Explicit 285 Specifies whether the control will be compiled with Option Explicit turned on. Allowed values are true and false . The default is true . See Chapt er 2 for a discussion of this compiler option. Inherits Specifies a class from which the compiled control class will inherit. The value can be the name of any accessible class that inherits from the UserControl class defined in the System.Web.UI namespace. If this attribute is not specified, the compiled control class inherits directly from the UserControl class. Language Specifies the programming language in which embedded code is written. This can be different from the language in which the controls code-behind class is written. Src Specifies a file containing the source for the controls code-behind class, if any. By default, user controls dont have a code-behind class. Strict Specifies whether the control will be compiled with Option Strict turned on. Allowed values are true and false . The default is false . See Chapt er 2 for a discussion of this compiler option. WarningLevel Specifies the warning level at which the compiler aborts compilation of the control. Allowed values are , 1 , 2 , 3 , and 4 . Implements Specifies the name of an interface that is implemented by the web page. This directive serves the same function as the Implements statement in Visual Basic .NET. The Implements directive has one attribute: Interface Designates the implemented interface. Only one interface can appear in each Implements directive. To specify more than one interface, provide multiple Implements directives. Recall that .aspx files are compiled into classes. This is why a web page can implement an interface. The actual implementation must be provided just as it would be in a Visual Basic .NET class definition. In this case, however, the implementation appears as Visual Basic .NET code within a script block in the .aspx file. Import Imports a namespace into the page, allowing classes to be referred to by their short names rather than by their fully qualified names. This directive serves the same function as the Imports keyword in Visual Basic .NET. The Import directive has one attribute: Namespace 286 Designates the namespace to import. Only one namespace can appear in each Import directive. To import more than one namespace, provide multiple Import directives. Only namespaces that exist within referenced assemblies can be included in the Import directive. In Visual Studio .NET projects, referenced assemblies appear beneath the References item in the Solution Explorer window. You can add assembly references to the project by right-clicking on the References item, selecting Add Reference, and then choosing or browsing to the desired assembly in the Add Reference dialog box. In projects that are created without the aid of Visual Studio .NET, assemblies are referenced in one of three ways. Assemblies that are in the global assembly cache GAC can be referenced by using the Assembly directive. Assemblies that are not in the GAC can be referenced by placing them in a bin directory within the applications root directory. Finally, at the command line, the DLL in which an assembly resides can be referenced using the reference or r switch. See also the Reference directive later in this list. OutputCache Specifies output cache settings. Aside from the attributes listed here, caching is not discussed in this book. Duration The number of seconds to cache the page or user control. There is no default—this attribute must be specified if the OutputCache directive is used. Location The location of the output cache. Allowed values are Any allows the framework to choose where to place the cache, Client the cache is placed on the browser client, Downstream the cache is placed on a server that is downstream from the server processing the request, None output is not cached, and Server the cache is placed on the server processing the request. The remaining attributes, VaryByCustom , VaryByHeader , VaryByParam , and VaryByControl , are beyond the scope of this book. Page Modifies compilation of a web page. This directives attributes are: AspCompat Indicates whether to run this page on a single-threaded apartment STA thread. Allowed values are true and false . The default is false . Running the page on an STA thread lets it call components that require an STA thread, such as components written in Visual Basic 6. In spite of its name, this attribute doesnt enable embedding classic ASP in an ASP.NET .aspx source file. AutoEventWireup 287 Indicates whether the pages events are autowired to appropriate handlers found within the Page class. Allowed values are true and false . The default is true . See Sect ion 6.2.1 in Sect ion 6.2 earlier in this chapter. Buffer Indicates whether to enable response buffering for the page. Allowed values are true and false . The default is true . When response buffering is enabled, the entire response is generated before any of it is sent to the browser. If response buffering is disabled, data is sent to the browser as it is generated. ClassName Specifies a class name for the compiled page. This can be any name that is valid for a Visual Basic .NET class. By default, the name is constructed from the filename of the web page. If the filename is filename.aspx , the ClassName value is filename_aspx . ClientTarget Overrides the ASP.NET frameworks automatic detection of browser capabilities. Set this attribute to Uplevel or Downlevel to force ASP.NET to forego browser detection and just assume the corresponding capabilities. Alternatively, set this attribute to the value given by the browser setting within the browserCaps section of a web applications .config file to cause ASP.NET to assume the capabilities defined within that section. The default is an empty string. This attribute corresponds to the ClientTarget property of the Page class. CodeBehind Used by Visual Studio .NET projects instead of the Src attribute to specify a code-behind file. CodePage Specifies the code page that is, the character set to use in rendering the web page. The value can be any valid code page. The default is the default code page for the web server. CompilerOptions Specifies arbitrary arguments to be passed to the Visual Basic .NET compiler. The format of these arguments is the same as for the Visual Basic .NET command-line compiler. The default is the empty string. Command-line compiler options are not documented in this book. ContentType Specifies the type of data to be rendered by the page. The value can be any valid content type as defined by the Multipurpose Internet Mail Extensions MIME specification. The default is texthtml . Culture Specifies the culture to be used by the page. The culture specifies language and formatting conventions used in rendering content. The value can be any standard culture name, as given in Appendix C . The default is determined by the configuration of the web server. Debug 288 Specifies whether to compile the page in debug mode. Allowed values are true and false . The default is false . Compiling in debug mode enables features such as rich error messages suitable for developers and setting breakpoints. Description Provides a place for the developer to describe the page. Neither ASP.NET nor Visual Studio .NET uses it in any way. EnableSessionState Specifies the availability of session state for the page. Allowed values are true indicating that session state is to be enabled, false indicating that session state is not to be enabled, and ReadOnly indicating that session state is enabled, but read-only. The default is true . See Sect ion 6.8 later in this chapter for more information. EnableViewState Specifies whether view state will be maintained across page requests. Allowed values are true and false . The default is true . See Sect ion 6.8 in this chapter for more information. EnableViewStateMac Specifies whether to use increased security to verify that the user has not tampered with the view state received in a postback. Allowed values are true and false . The default is false . ErrorPage Specifies the URL of a web page to which the user should be redirected if an unhandled exception occurs during the processing of the page request. Note that this redirection occurs only if custom errors are enabled. This is controlled by the customErrors section in the applications web.config file or in the machines machine.config file. By default, the machine.config file contains this entry: customErrors mode=RemoteOnly This means that if an unhandled exception occurs, redirection to the page specified by the ErrorPage attribute occurs only if the browser is not running on the web server. This is a good default configuration, since a developer testing on a web server probably would like to see the IIS-generated exception page rather than a customer-friendly error page. See Chapt er 3 for more information about configuration files. Explicit Specifies whether the page will be compiled with Option Explicit turned on. Allowed values are true and false . The default is true . See Chapt er 2 for a discussion of this compiler option. Inherits 289 Specifies a class from which the compiled page class will inherit. The value can be the name of any accessible class that inherits from the Page class defined in the System.Web.UI namespace. If this attribute is not specified, the compiled page class inherits directly from the Page class. Language Specifies the programming language in which embedded code is written. This can be different from the language in which the pages code-behind class is written. LCID Specifies the locale to be used by this page LCID stands for locale identifier . The LCID is a four-byte unsigned integer that identifies the culture used when rendering the page. Specifying a value for LCID is an alternative to specifying a value for the Culture attribute. See Appendix C for a list of cultures and corresponding LCIDs. ResponseEncoding Specifies the character-encoding format to use for the web page. The default is UTF-8 . Src Specifies the name of a file containing the source for the pages code-behind class, if any. By default, web pages dont have a code-behind class. Strict Specifies whether the page will be compiled with Option Strict turned on. Allowed values are true and false . The default is false . See Chapt er 2 for a discussion of this compiler option. Trace Specifies whether to enable tracing. Allowed values are true and false . The default is false . TraceMode When tracing is enabled, specifies how trace messages will be sorted. Allowed values are SortByCategory and SortByTime . The default is SortByTime . Transaction Specifies whether and how the page participates in transactions. Allowed values are NotSupported , Supported , Required , and RequiresNew . The default is NotSupported . Transaction processing is not discussed in this book. WarningLevel Specifies the warning level at which the compiler aborts compilation of the page. Allowed values are , 1 , 2 , 3 , and 4 . Reference 290 Provides a way to reference the data type for a control or page, which will be dynamically loaded from the current page using the Page classs LoadControl method. This directives attributes are: Page The name of an .aspx file that defines a web page to be dynamically referenced from the current page. Control The name of an .ascx file that defines a web control to be dynamically referenced from the current page. Only one attribute either Page or Control is allowed in a single Reference directive. To specify multiple pages or controls, specify multiple Reference directives on separate lines. The Reference directive is useful if the page has code similar to this: script language=VB runat=server Protected Overrides Sub OnLoadByVal e As EventArgs Dim ctl As Control ctl = LoadControlSomeControl.ascx Controls.Addctl End Sub script This code loads a control from an .ascx file and adds it to the current pages collection of controls. This works just fine, but if this code needs to access properties and methods of the loaded control without resorting to late binding, its in trouble. It has no way to convert the Control reference in ctl to the appropriate data type. This is where the Reference directive comes in. Referencing the .ascx file in an Reference directive makes the data type available to the source code on the rest of the page. Heres how it would look: Reference Control=SomeControl.ascx script language=VB runat=server Protected Overrides Sub OnLoadByVal e As EventArgs Dim ctl As SomeControl ctl = CTypeLoadControlSomeControl.ascx, SomeControl ctl.SomeProperty = SomeValue Controls.Addctl End Sub script ctl is now strongly typed, and the type SomeControl is available to the application code. Register Allows user controls and custom server controls to be added to a web page. It has two forms. The first form allows all the controls in an entire namespace to be referenced. It looks like this: Register TagPrefix=tagprefix_name Namespace=namespace_name Assembly=assembly_name 291 When this format is used, you can use any of the controls within the referenced namespace on the web page by including a tag of this form: tagprefix_name:class_name runat=server The second form of the Register directive registers a single control that resides in a source file. It looks like this: Register TagPrefix=tagprefix_name TagName=tagname Src=path When this format is used, you can use the specific control found in the source file on the web page by including a tag of this form: tagprefix_name:tagname runat=server In either form, you can set properties of the control object by specifying the properties as attributes of the tag, like this: tagprefix_name:tagname MyPropertyName=some value runat=server See Sect ion 6.11 later in this chapter for additional examples. The attributes of the Register directive are: TagPrefix A name that represents the namespace being referenced TagName A name that represents the class being referenced Namespace The namespace to reference Src The source file containing the control

6.6 ASP.NET Objects: Interacting with the Framework