Page #41 (Chapter 5 - Securing an IIS Application) | Visual Basic Developer[ap]s Guide to ASP and IIS

	Chapter 5 - Securing an IIS Application
	Visual Basic Developers Guide to ASP and IIS
	A. Russell Jones


	Create an HTML Template


	Now you're going to add an HTML template. The process of editing HTML templates or files is not part of VB (yet), so you'll need to create a new template with another program.


	Listing 5.1 shows the HTML for the sign-on screen. To create a new HTML template file, open an HTML or text editor—Notepad works fine—and enter the code in Listing 5.1. Alternately, you can download the code and graphics for this project from the Sybex Web site.


	Note		When you copy HTML from this book, ignore the line breaks; the HTML parser ignores them as well. It's perfectly acceptable (and somewhat faster) to format the entire HTML screen as a single unbroken string of text. Of course, if you do this, the source code in the browser becomes difficult to read.


	Note		To download code, navigate to http://www.sybex.com. Click the Catalog button and search for this book's title. Click the Downloads button and accept the licensing agreement. Accepting the agreement grants you access to the downloads page for the book.


	Listing 5.1: HTML for Sign-On Screen (Signon.htm)


	<html>

<head>

<title>Signon</title>

</head>

<P><font size="5">Please Sign In</font></P>

Enter your sign-on and password, then click the Signon button<BR>

<tr>

<b>Signon:</b>

</td>

</td>

</tr>

<tr>

<b>Password:</b>

</td>

</td>

</tr>

<tr>

</td>

</tr>

</table>

</form>

</center>

</body>

</html>


	Save the completed HTML template file as Signon.htm in the SecuredSite\HTMLTemplates directory.


	Tip		VB always makes a copy of HTML templates that you add to the WebClass. It never uses an HTML template directly. If you don't create a separate directory for the templates, VB will rename them for you. For example, when you add an HTML template file named Template1.htm, VB will copy the file to Template11.htm. It quickly becomes difficult to keep track of the names. You can avoid this problem altogether by storing the original copy of your templates in a directory other than your project directory.


	Now add the template to the WebClass. Right-click the HTML Template Web-Items entry in the WebClass Designer and select Add HTML Template. Select the Signon.htm file you just saved from the HTMLTemplates directory. Behind the scenes, VB will copy the file, parse the HTML in it, and create a new item called Template1. Right-click the Template1 item, select Rename from the pop-up menu, and rename the item Signon. Your screen should now look like Figure 5.5.


	The right-hand pane of the designer lists the programmable items that the HTML Template parser found in the HTML file. In DHTML, all these objects expose events, methods, or properties that you can alter at runtime. You'll connect some of these events later.


	For now, click the Signon item and look at the Properties window. HTML Templates have three properties at design time, as shown in Table 5.2.


	Table 5.2: HTML Template Design-Time Properties


	Property


Description


	Name


The class name of this HTMLTemplate object. Use this name to refer to the object within the project.


	ReScanReplacements


This Boolean property controls whether the tag replacement engine scans once for replacement tags or whether it scans continuously until it has replaced all the tags. This concept is confusing until you realize that you can replace tags with content containing other tags. If you need to do this, set ReScanReplacements = True; otherwise, leave it set to False.


	TagPrefix


The default setting WC@ is a bug. Although it works most of the time, Micro-soft recommends that you change it to WC: without the ampersand. I've found the colon to be unnecessary. (See the Microsoft Knowledge Base Article Q189539 for more information.)


	Leave the ReScanReplacements setting set to False. Change the TagPrefix setting to WC, without the default ampersand, then save the project.


	The HTML file contains three WebClass replacement tags: WCMessage, WCSignon, and WCPassword.


	Note		The HTML Template parser often changes the case of WebClass replacement tags. If you edit the Signon template after adding it to the WebClass, you will probably see that the tags have changed to WCMESSAGE, WCSIGNON, and WCPASSWORD. The change to uppercase is inconsistent. For example, if you enter the tags in the template in all lowercase, the HTML Template parser changes only the second tag to uppercase, which will cause a runtime error.


	In the file, these replacement tags appear as block elements, with a starting and ending tag, for example, <WCMessage></WCMessage>. Both tags must be present and, except for the slash, the contents must match for the replacement to work properly. Case is relevant. Let me restate that a little louder: CASE MATTERS! Mismatched tags cause a runtime error, not a design-time error, probably because the WebClass HTML parser, like other HTML parsers, is not case sensitive. If you have mismatched tags in a template, the WebClass will generate an error similar to this in the Application event log:


	WebClass Runtime error '800a2332'

Corresponding close tag, </WCSignon>, not found in <file>


	Tip		Always check the Application event log for errors if your WebClass application behaves in an unexpected manner.


	Unfortunately, this first version of WebClasses doesn't have a very "smart" HTML parser. It often alters your HTML code in irritating ways, such as removing or adding white space, changing the case of WebClass tags, or rewriting angle brackets as HTML encoded text (for example, < becomes < and > becomes >). The parser is also unable to correctly parse embedded WebClass tags (tags contained within tags). For this reason, Microsoft recommends that you insert WebClass tags only as markers for complete replacement of tags, not as markers for single parameters. For example, the following WebClass tag will be replaced at runtime with an <input> tag.


	<WCTextInput1>Insert input tag</WCTextInput1>


	In contrast, the parser will not correctly parse the following HTML tag because it contains an embedded WebClass tag:


	<input type="text" value="<WCTextInput1></WCTextInput1>">


	If you look at Listing 5.1, you'll see that it follows Microsoft's recommendation.


	Because the HTML parser sometimes changes the case of your WebClass tags, you should always force the tag names to either uppercase or lowercase in comparison tests. Alternately, you can always write your WebClass tags in uppercase to begin with. Remember, though, humans are fallible; your programs will work better if you write the tags however you like, then force the case conversion before any tag comparison.


	You need to tell the WebClass which item to display first. Right-click the Signon HTML Template and select View Code from the pop-up menu. Find the WebClass_Start event. VB automatically inserts some default response code in the Start event:


	'Write a reply to the user

With Response

.Write "<html>"

.Write "<body>"

.Write "<h1><font face=""Arial"">" & _

"WebClass1's Starting Page</font></h1>"

.Write "<p>This response was created " & _

"in the Start event of WebClass1.</p>"

.Write "</body>"

.Write "</html>"

End With


	You'll want to delete that default response code in almost every case and substitute your own Start code. In this case, the first thing you want to do is display the Signon screen. You use the NextItem property to control which item the WebClass will process next.


	Private Sub WebClass_Start()

Set NextItem = Signon

End Sub


	Tip		To eliminate the default Start event code altogether, use Notepad or another text editor to open the file WebClass.dsr from the Template\Projects directory where you installed VB. Scroll to the bottom of the file and delete the contents of the WebClass_Start event. Save the file. The next time you create an IIS project, the default Start event code will not appear.


	Unlike standard VB classes, you can't refer to the WebClass itself with the keyword Me. You can refer to any WebClass generically using the syntax WebClass .propertyName or WebClass_methodName. Note that WebClass in the preceding sentence does not stand for the name of your WebClass; use the word WebClass itself.


	When the WebClass executes the NextItem command, it calls the Respond method for the specified item. In the Respond event for the Signon item, tell the item to display itself:


	Private Sub Signon_Respond()

On Error Goto ErrSignon_Respond

Signon.WriteTemplate

ExitSignon_Respond:

Exit Sub

ErrSignon_Respond:

Response.Write "Error: " & Err.Number & "<br>" & Err.Source & _

"<br>" & Err.Description

Resume ExitSignon_Respond

End Sub


	Warning		You should always trap for errors that may occur during the WriteTemplate method. When an error occurs at runtime during HTML template processing, the WebClass fires the FatalErrorEvent event. Unfortunately, the WebClass clears the Error object before the FatalErrorEvent occurs, so the only way to find the error is to look in the Application event log.


	The WriteTemplate method loads the HTML template file, then scans for replacements. Each time the scanner finds a replacement tag, it calls the Process-Tag event for the item. Although WebClasses automate the process of making the replacement, you need to write code to tell VB which tags to replace, and what content to replace each tag with. In this program, you'll replace all three tags. Enter this code into the Signon_ProcessTag event:


	Private Sub Signon_ProcessTag(ByVal TagName As String, _

TagContents As String, SendTags As Boolean)

Select Case lcase(TagName) ' note forced case conversion

Case "wcmessage"

TagContents = Session("msg")

Session("msg") = ""

Case "wcsignon"

TagContents = "<input type=""text""" & _

"name=""Signon"" value=""" & _

Session("LastSignon") & """>"

Case "wcpassword"

TagContents = "<input type=""password""" & _

"name=""Password"" value=""" & _

Session("LastPassword")& """>"

End Select

End Sub


	The ProcessTag event occurs before a WebClass sends HTML to the browser. The WebClass looks for replacement tags in a WebItem only if it's based on an HTML template, and it always looks for the replacement tags unless you set the TagPrefix property of the WebItem to a null string. The WebClass never fires the ProcessTag event for a custom WebItem.


	The following list shows the three arguments passed to the ProcessTag event and their purposes.


	TagName Contains the name of the replacement tag—the text inside the brackets.


	TagContents Contains the text between the start and end replacement tag, for example, for the tag <WCSignon>Signon</WCSignon>, the Tag-Contents would contain Signon, whereas the TagName would contain WCSignon.


	SendTags This flag controls whether the WebClass sends the replacement tags along with the replacement value or replaces the tags with the replacement value—in other words, does not send the tags. Here's the difference:


	If your WebClass Tag = <WCSignon></WCSignon>, then the TagName= "WCSignon". Assume you set the TagValue to Bill.


	When SendTags=True, the string sent to the browser contains <WCSignon> Bill </WCSignon>.


	When SendTags=False, the string sent to the browser contains only Bill.


	The default is False.


	The ProcessTag event code replaces the three WebClass tags, (WCMessage, WCSignon, and WCPassword) with temporary values stored in Session variables called msg, lastSignon, and lastPassword, respectively. During the first replacement, the Session variables have no value—or rather, they have a variant subtype of Empty, so they're interpreted as null strings.


	Tip		Using the same variable names in all the various layers of code is good practice when possible; you'll find that Web applications typically pass values from databases to business objects, to WebClasses, to the browser, to client-side script or input tags, and often back again. Your applications will be much easier to debug and maintain if you name the variables consistently in all these locations.