ASP.NET.in.a.Nutshell.Second.Edition [Electronic resources] نسخه متنی

18.3 Methods Reference

Server.ClearError( )

Clears the last exception thrown.

Parameters

None

Notes

The ClearError method is new to ASP.NET. You can use this method at
the beginning of page processing to clear the last exception so that
the information provided by the GetLastError method is specific to an
exception occurring on the current page.

objvar = Server.CreateObject(ProgID)
objvar = Server.CreateObject(Type)

Returns a reference to a COM object created based on the supplied
ProgID.

Parameters

objvar

A variable of type Object to receive the reference to the newly
created object.

ProgID

A String variable or literal containing the COM programmatic ID of
the desired object.

Type

The type name of a runtime callable wrapper (RCW)
class that the

tlbimp.exe utility generated to
expose a COM object to managed code.

Example

The code example declares an object variable, uses
Server.CreateObject to assign a reference to a newly created ADO
Recordset object to the variable, and then opens the recordset and
returns the RecordCount property to the browser by using the Message
label control:

Sub Page_Load( )
Dim rs1
Dim ConnString As String
ConnString = "driver={SQL Server};server=(local)\NetSDK;"
ConnString =  ConnString & "database=Pubs;Trusted_Connection=yes"
rs1 = Server.CreateObject("ADODB.Recordset")
' 1 and 3 are the values for adOpenKeyset and adLockOptimistic
rs1.Open("SELECT * FROM Authors", ConnString, 1, 3)
Message.Text = "There are " & rs1.RecordCount & _
" records in the Authors table.<br/>"
End Sub

Figure 18-1 shows the output of a page that combines
the example for the CreateObject method with the example for the
CreateObjectFromClsid method.

Figure 18-1. Output of CreateObject and CreateObjectFromClsid examples

Notes

This method enables backward compatibility with classic ASP
applications and allows the late-bound use of COM components in
ASP.NET applications. For new development, it is preferable to use
other means to achieve the results that this method was used for in
classic ASP. These means include:

• Using the

  TlbImp.exe utility to create a RCW for
  the component, which enables early binding and optimizes the
  performance of calls between managed and unmanaged code. If you add a
  reference to a COM component in the Visual Studio .NET IDE, the RCW
  is created for you automatically.

• Rewriting custom COM components to run in the managed environment.
  This method is preferable, as it entirely eliminates the marshalling
  cost of switching between managed and unmanaged code.

It is important for you to consider the second alternative for COM
components that are called frequently and perform a little work each
time they're called (as opposed to components that
are called once and perform larger amounts of work per call). The
distinction between these models is often referred to as
"chatty" versus
"chunky" communications. The cost
of chatty components in marshalling between managed and unmanaged
code tends to be significantly higher compared to the amount of work
being done in each call. When upgrading COM components to run in the
managed environment, you should convert chatty components first and
then look at chunky components.

If you want ASP.NET to fire the OnStartPage and OnEndPage events used
in some COM components to access the ASP intrinsics, you must add the
ASPCompat attribute to the page's
@ Page directive:

<%@ Page ASPCompat="true" %>

When ASPCompat is set to True,
ASP.NET creates unmanaged intrinsic objects to pass to the
component's OnStartPage method. ASP.NET also
switches from executing in multithreaded apartment (MTA) to
single-threaded apartment (STA) mode to ensure compatibility with COM
components created in Visual Basic 5 or 6. This can have a
significant negative impact on performance, so be sure to test your
application carefully to determine whether the performance will be
acceptable when using this attribute.

In ASP.NET, unlike in ASP, it isn't necessary to use
the Set keyword with CreateObject, as shown in the
previous example. It also isn't necessary to use
Set objName
= Nothing to release the
reference to the object, since the managed reference is eventually
garbage collected, at which point the COM object is dereferenced and
destroyed.

objvar = Server.CreateObjectFromClsid(Clsid)

Returns a reference to a COM object created based on the supplied COM
CLSID.

Parameters

objvar

A variable of type Object to receive the reference to the newly
created object.

Clsid

A String variable or literal containing the COM CLSID (a type of
globally unique identifier (GUID) for the component that is found in
the Registry) of the desired object.

Example

The code example declares an object variable, uses
Server.CreateObjectFromClsid to assign a reference to a newly created
ADO Recordset object to the variable, and then opens the recordset
and returns the RecordCount property to the browser using the Message
label control.

Sub Page_Load( )
Dim rs1
Dim ConnString As String
ConnString = "driver={SQL Server};server=(local)\NetSDK;"
ConnString =  ConnString & "database=Pubs;Trusted_Connection=yes"
rs1 = Server.CreateObjectFromClsid( _
"00000535-0000-0010-8000-00AA006D2EA4")
' 1 and 3 are the values for adOpenKeyset and adLockOptimistic
rs1.Open("SELECT * FROM Titles", ConnString, 1, 3)
Message.Text &= "There are " & rs1.RecordCount & _
" records in the Titles table.<br/>"
End Sub

Notes

This method is new to ASP.NET and, like the CreateObject method, it
allows the late-bound use of COM components in ASP.NET applications.

The other notes relating to the CreateObject method also apply
equally to the CreateObjectFromClsid method.

Server.Execute(Path)
Server.Execute(Path, Writer)

Executes a request on the URL passed by the
Path argument and optionally captures the
output of the requested page by using an instance of the
TextWriter class supplied by the
Writer argument.

Parameters

Path

A String variable or literal specifying the URL to execute. The URL
passed to the Execute method may be absolute (containing all the
information needed to locate the resource, including the protocol
type and server name) or relative (containing only the relative path
of the resource).

Writer

An instance of any class derived from the
TextWriter class (found in the System.IO
namespace); used to capture the output of the execution of the
requested URL.

Example

The code example declares a string variable, creates a new
TextWriter, and then calls Server.Execute to execute a page based on
the CreateObject example code and capture its results. Figure 18-2 shows the output of the example.

Figure 18-2. Output of CreateObject and CreateObjectFromClsid examples

Sub Page_Load( )
Dim Url As String = "CreateObject.aspx"
Dim sw As New System.IO.StringWriter( )
Server.Execute(Url, sw)
Message.Text = "Request output:<br/><br/>" & sw.ToString( )
End Sub

Notes

The Execute method is a useful feature that first appeared in the IIS
5.0 version of Active Server Pages. ASP.NET includes an overloaded
version of the method, adding the Writer
argument for capturing, manipulating, and/or saving the output of the
request being executed.

When called passing only the URL, the Execute method automatically
inserts the output of the request into the HTML output stream of the
calling page.

When called passing both the URL and an object reference derived from
the TextWriter class (such as StringWriter,
StreamWriter, or HtmlTextWriter), the output is not automatically
added to the HTML output stream, but may be obtained, as in the
previous example, by calling the ToString method of the writer class.

LastException = Server.GetLastError( )

Returns the last exception thrown.

Parameter

LastException

An object of type Exception to receive the
application's last exception.

Example

The code in

GetLastError.aspx displays a button
that, when clicked, calls a server-side event handler that declares
three Integers and purposely divides by zero (a no-no) to cause an
exception. The code in the Page_Error event handler declares an
Exception object and a String, gets the Exception using GetLastError,
tests whether the object reference is valid and assigns the Message
property of the exception to the string variable, and then writes the
value to the browser using the Response.Write method. You can also
call the GetLastError method from the Application_Error event
handler, which you can place in the

global.asax
file to catch errors that have not been handled at the page level.

<%@ Page Language="VB" %>
<html>
<head>
<title>Examining the Last Error</title>
<script runat="server">
Sub CauseError(sender As Object, e As EventArgs)
Dim x, y, z As Integer
y = 1
z = 0
x = y / z
End Sub
Sub Page_Error(Source As Object, E As EventArgs)
Dim LastError As Exception
Dim ErrMessage As String
LastError = Server.GetLastError( )
If Not LastError Is Nothing Then
ErrMessage = LastError.Message
Else
ErrMessage = "No Errors"
End If
Response.Write("Last Error = " & ErrMessage & "<br/><br/>")
Server.ClearError( )
End Sub
</script>
</head>
<body>
<form runat="server">
<h4><font face="verdana">Cause an Error to Occur...</font></h4>
<asp:button text="CauseError" OnClick="CauseError" runat="server"/>
</form>
</body>
</html>

Notes

You'll find this method useful for getting
information about an error from a custom error-handling page.
GetLastError returns information only when called in the Page_Error
or Application_Error event handlers because once these events have
been fired, the exception is cleared automatically.

returnstring = Server.HtmlDecode(s)
Server.HtmlDecode(s,output)

Returns a string in which any HTML information encoded by the
HtmlEncode method (described later in this chapter) is decoded back
into its standard HTML format.

Parameters

returnstring

A String variable to receive the decoded string from the method.

s

A string variable containing the encoded HTML that the method will
decode.

output

An instance of any class derived from the
TextWriter class (found in the System.IO
namespace) used to capture the decoded string.

Example

The code example declares two string variables, sets the value of
StrToDecode to the encoded equivalent of
<p>Hello,
World!</p>, assigns the return value of the
Server.HtmlDecode call to StrToReturn, and then
writes the value to the browser using the Message label control:

Sub Page_Load( )
Dim StrToDecode As String
Dim StrToReturn As String
StrToDecode = "<p>Hello, World!</p>"
StrToReturn = Server.HtmlDecode(StrToDecode)
Message.Text = StrToReturn
End Sub

Notes

This method provides a simple way to undo the effects of calling
HtmlEncode on a given string. You can also use it as an educational
tool to demonstrate the relationship between various characters used
in HTML and ASP (such as the greater-than (>) and less-than (<)
symbols) and their encoded equivalents.

When called with only the s argument, this
method returns a string. When called with both an
s argument and an
output argument (such as a
StringWriter or HtmlTextWriter
class instance), the method does not return a value; instead, you can
obtain the decoded string by calling the ToString method of the
writer object.

While this method is useful, you probably won't use
it as frequently as its cousin, UrlDecode, which is described later
in this chapter.

returnstring = Server.HtmlEncode(s)
Server.HtmlEncode(s, output)

Returns a string in which any HTML tags found are encoded by using
the HTML literal equivalents of symbols such as >
(&gt;), < (&lt;),
and even quotes (&quot;). This allows
developers to display HTML and ASP source code on the page, rather
than treating it as rendered output or code to execute.

Parameters

returnstring

A String variable to receive the encoded string from the method.

s

A string variable containing the HTML that the method will encode.

output

An instance of any class derived from the
TextWriter class, such as a
StringWriter class instance (found in the
System.IO namespace), used to capture the encoded string.

Example

The code example declares two string variables, sets the value of
StrToEncode, assigns the return value of the
Server.HtmlEncode call to StrToReturn, and then
writes the value to the browser using the Message label control. Note
that you have to view the HTML source to see the actual string
returned by the method call.

Sub Page_Load( )
Dim StrToEncode As String
Dim StrToReturn As String
StrToEncode = "<%@ Page Language="VB" %>"
StrToReturn = Server.HtmlEncode(StrToEncode)
Message.Text = StrToReturn
End Sub

Notes

This method is great for displaying the source of a page for
educational purposes. It is also particularly useful for encoding
text entered by users that may or may not be displayed or written to
the browser. Without this encoding (or some form of filtering or
validation of the input), it might be possible for the user to enter
script or other code that the browser or server could execute. This
possibility could pose a very large security risk.

Whether with HtmlEncode or with some form of filtering or validation,
you should always ensure that text entered by your users that will be
used or displayed by your application does not contain unexpected
characters or content.

Like the HtmlDecode method, HtmlEncode is overloaded. It returns a
string when called with the s argument
alone, and it does not return a value when called with both an
s and an output
argument. Instead, it sends the encoded HTML to the
output class instance.

PhysicalPath = Server.MapPath(Path)

Returns a string containing the physical path in the
server's filesystem that corresponds to the virtual
or relative path specified by the Path
argument.

Parameters

PhysicalPath

A String variable to receive the physical path from the method.

Path

A String variable containing the virtual or relative path to be
mapped.

Example

The code example declares two string variables, sets the value of
RelativePath, assigns the return value of the
Server.MapPath call to PhysicalPath, and then
writes the value to the browser by using the Message label control:

Sub Page_Load( )
Dim RelativePath As String
Dim PhysicalPath As String
RelativePath = "HtmlEncode.aspx"
PhysicalPath = Server.MapPath(RelativePath)
Message.Text = PhysicalPath
End Sub

Notes

You can use this method to determine the physical location for
creating a new file in response to a user action or code event.

In classic ASP, attempting to use this method with the MS-DOS (.) and
(..) relative directory syntax would result in an error. In ASP.NET,
no error occurs. In the previous example, using
"../HtmlEncode.aspx" for the
Path returns a physical path mapping the
file

HtmlEncode.aspx to the parent folder of its
physical location. Using "./HtmlEncode.aspx" for
the Path returns the same physical path
mapping as in the original example.

The MapPath method dynamically determines whether the provided path
is a relative or virtual path based on whether the leading character
is a slash (/) or backslash (\). If the leading character is either
one, the path is assumed to be a complete virtual path. If not, the
path is assumed to be relative to the physical path of the currently
executing page.

If the last component in Path is a
filename, the MapPath method does not verify its existence. In other
words, the code example returns the same absolute path whether or not

HtmlEncode.aspx exists.

A more flexible version of the MapPath method has been added to the
Request object that enables you to specify a base directory for
resolving mappings and lets you allow mapping of paths across
different applications. You can read more about the Request.MapPath
method in Chapter 16.

Server.Transfer(Path)
Server.Transfer(Path, preserveForm)

Discontinues execution of the current page and transfers execution to
the page specified by the Path argument.
This allows control of an application to be redirected to the page
specified by the Path argument without any
response being sent to the client.

In contrast to the Execute method, which returns control to the page
in which it is called once the page specified in the Execute method
finishes processing, the Transfer method does not return control to
the calling page.

Parameters

Path

A String variable containing the path to the page to which execution
will be transferred.

preserveForm

A Boolean variable that indicates whether the Form and QueryString
collections should be cleared before transferring control to the page
that the Path argument specifies.

Example

The code example declares a string variable containing the name of
the page to transfer control to, and then calls Server.Transfer. Note
that the call that sets the Message.Text property will never be
executed.

Sub Page_Load( )
Dim Url As String = "CreateObject.aspx"
Server.Transfer(Url)
Message.Text = "This code will never be executed!"
End Sub

Notes

The ability to clear the Form and QueryString collections prior to
passing control to the page that the Path
argument specifies is new in ASP.NET. This is convenient for passing
control to pages that you did not create and that might break if they
encounter unexpected values, or if you want to keep the Form or
QueryString contents private. If you do not pass a
preserveForm argument, the default
behavior is for the Form and QueryString collections to be preserved.

Make sure that no code in your page must execute after a
Server.Transfer. If you have such code, you may want to consider
using Server.Execute instead.

returnstring = Server.UrlDecode(s)
Server.UrlDecode(s,output)

Returns a string in which any special character sequences resulting
from encoding by the UrlEncode method (described later in this
chapter) are decoded back into the original format. For example, a
URL with a query string such as:

http://localhost/ASPdotNET_iaN/Chapter_18/UrlDecode. aspx?strtodecode=This%20is%20a%20good%20string.

would return the following string from the UrlDecode method:

This is a good string.

Parameters

returnstring

A string variable to receive the decoded string from the method.

s

A string variable containing the encoded URL to be decoded by the
method.

output

An instance of any class derived from the
TextWriter class (found in the System.IO
namespace) used to capture the decoded string. Examples are the
StringWriter and HtmlTextWriter
classes.

Example

The code example declares two string variables, sets the value of
StrToDecode to the encoded equivalent of the
QueryString's StrToDecode value,
assigns the return value of the Server.UrlDecode call to
StrToReturn, and then writes the value to the
browser using the Message label control:

Sub Page_Load( )
Dim StrToDecode As String
Dim StrToReturn As String
StrToDecode = Request.QueryString("StrToDecode")
StrToReturn = Server.UrlDecode(StrToDecode)
Message.Text = StrToReturn
End Sub

Notes

New in ASP.NET, this method provides a simple way to undo the effects
of calling UrlEncode on a given string. It is especially useful for
retrieving values passed in the query string, since these values
commonly contain characters, such as spaces and commas, that are not
allowed in URLs.

When called with only the s argument, this
method returns a string. When called with both the
s argument and
output argument, the method does not
return a value; instead, the decoded string is sent to the
output writer.

returnstring = Server.UrlEncode(s)
Server.UrlEncode(s, output)

Returns a string in which any characters not allowed in URLs are
encoded by using the URL literal equivalents, such as %2c for comma
and + for space. This makes it very simple to pass any string as a
query string value and, thanks to the new UrlDecode method, just as
simple to retrieve the unencoded value.

Parameters

returnstring

A String variable to receive the encoded string from the method.

s

A String variable containing the value to be encoded by the method.

output

An instance of any class derived from the
TextWriter class (found in the System.IO
namespace); used to capture the encoded string. Classes derived from
TextWriter include StringWriter and HtmlTextWriter.

Example

The code example declares two string variables, sets the value of
StrToEncode, assigns the return value of the
Server.UrlEncode call to StrToReturn, and then
writes the HTML anchor tag containing a query string with the encoded
value to the browser using the Message label control:

Sub Page_Load( )
Dim StrToEncode As String
Dim StrToReturn As String
StrToEncode = "Hello, World!"
StrToReturn = Server.UrlEncode(StrToEncode)
Message.Text = "<a href="UrlDecode.aspx?StrToDecode=" & StrToReturn
Message.Text &= "">" & StrToReturn & " - Click to Decode!</a>"
End Sub

Notes

This method replaces non-URL-allowable characters in strings that
need to be passed as part of a URL. For example, one of the most
difficult things to pass as part of a URL is another URL. The
UrlEncode method replaces all slash (/), dot (.), and colon (:)
characters for you. Figure 18-3 shows the output of
the previous example.

Figure 18-3. Output of server UrlEncode

Like the UrlDecode method, UrlEncode is overloaded. It returns a
string when called with the s argument
alone and does not return a value when called with both the
s and output
arguments. Instead, the encoded URL is sent to the writer object.

returnstring = Server.UrlPathEncode(s)

Returns a string containing a URL whose path portion is encoded using
the URL literal equivalents of symbols such as slash (/), colon (:),
and dot (.). The method also encodes any spaces in the remaining
portion of the URL, since spaces in the query string may be
unexpectedly truncated by some browsers.

Parameters

returnstring

A String variable to receive the encoded string from the method.

s

A String variable containing the URL to be encoded by the method.

Example

The code example declares two string variables, sets the value of
StrToEncode, assigns the return value of the
Server.UrlPathEncode call to StrToReturn, and then
writes the value to the browser as part of a hyperlink:

Sub Page_Load( )
Dim StrToEncode As String
Dim StrToReturn As String
StrToEncode = "http://www.aspnetian.com/Chapter18/UrlPathEncode.aspx"
StrToReturn = Server.UrlPathEncode(StrToEncode)
Message.Text = "<a href="UrlPathEncode.aspx?target=" & _
StrToReturn & "">" & StrToReturn & "</a><br/>"
Message.Text &= "Target = " & Request("Target")
End Sub

Notes

This method existed in classic ASP, but was undocumented.