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