Channel 9

Who Is Looking: Building a Custom ASP.NET Control that uses Javascript, Cascading Style Sheets, and Ajax

Stephen Walther — Sat, 05 May 2007 12:41:09 GMT

	In this article, Stephen Walther shows you how to create a custom ASP.NET control that uses Javascript, Cascading Style Sheets, and Ajax to display a list of people who are looking at a web page in real time. You learn how to create the WhoIsLooking control.
Stephen Walther Steve's Blog Difficulty: Advanced Time Required: Less than 1 hour Cost: Free Software: Visual Web Developer Express Visual Basic or Visual C# Express Editions, Hardware: Download: Download

I want to know who is looking at my websites. Don't get me wrong -- I'm not paranoid, I'm just curious (and maybe a little vain). After I have undergone all of the pain and effort of building a web page, I want to know that someone is actually looking at it.

Yes, yes -- I know about website statistics programs. But that is not what I want. I want to know who is visiting a web page right now in real time. Furthermore, I want to share this information with anyone else who is visiting the web page.

This month, we build a custom ASP.NET 2.0 control that displays a list of everyone who is currently looking at a particular web page (see Figure 1). The list rendered by the control is updated, in real time, using Javascript and Ajax. People pop in and out of the list as they visit and leave the web page. We create a control named the WhoIsLooking control.

Figure 1 - The WhoIsLooking control

The WhoIsLooking control is a complicated control. To get it to work, I had to take advantage of a number of advanced control building techniques. Therefore, this post is divided into several parts.

In the first part, I describe how you create custom controls for the ASP.NET 2.0 framework. After getting the basics out of the way, I explain how you can embed Javascript and Cascading Style Sheets in a custom control. Then, we explore the very trendy topic of Ajax. Finally, I discuss how you can grab information about the users viewing a web page.

If you want to play with the control right now, you can go ahead and click the download link at the top of this article to download all of the control source code (There is both a C# and VB.NET version of the source code). The download package also includes a test ASP.NET website that you can use to try out the control. When testing the control, open up multiple types of browsers and point them to the same page (If you open up multiple instances of Microsoft Internet Explorer, you'll see only one instance of the browser listed by the WhoIsLooking control since all instances of the same browser share the same set of cookies).

Creating Custom ASP.NET 2.0 Controls

All the ASP.NET 2.0 controls that you find in the Visual Studio toolbox, such as the GridView, TextBox, and TreeView controls, were created as custom controls. If you ever get bored of the standard controls, you always have the option of building new ones.

An ASP.NET control -- like just about everything else in the .NET framework -- is a class. Typically, a custom control is a class that derives from the WebControl class. Creating a custom control generally involves completing the following three steps:

(1) Add a new class to your website's App_Code folder

(2) Modify the class so that it derives from the base WebControl class

(3) Override the base WebControl class's RenderContents() method

One of my favorite new features of ASP.NET 2.0 is the magic App_Code folder. If you add the source code for a class to this special folder, the class gets compiled automatically. Since ASP.NET controls are just a type of class, this means that you can create a new ASP.NET control simply by adding the source for the control to the App_Code folder.

When you create a custom control, you typically derive the control from the base WebControl class (found in the System.Web.UI.WebControls namespace) and override the base class's RenderContents() method.

At its most basic level, a control is simply a class that renders content to a Web browser. In the RenderContents() method, you output the content that you want to send to the browser.

For example, Listing 1 contains the simplest control that I can imagine -- a Hello World control. This control renders the text “Hello World”.

Listing 1 -- HelloWorld.cs

using System;

using System.Web.UI;

using System.Web.UI.WebControls;

namespace myControls

{

  public class HelloWorld : WebControl

  {

    protected override void RenderContents(HtmlTextWriter writer)

    {

      writer.Write("Hello World");

    }

  }

}

Listing 1 -- HelloWorld.vb

Imports System

Imports System.Web.UI

Imports System.Web.UI.WebControls

Namespace myControls

  Public Class HelloWorld

    Inherits WebControl

    Protected Overrides Sub RenderContents(ByVal writer As HtmlTextWriter)

      writer.Write("Hello World")

    End Sub

  End Class

End Namespace

After you create a new custom control, you can add it to a page in one of three ways. The first option is to register the control in a particular page. For example, you can register the HelloWorld control in a page by adding the following directive to the page:

<%@ Register TagPrefix="custom" Namespace="myControls" %>

The value of the TagPrefix attribute can be anything you want. The value of the Namespace attribute must match the namespace that you declared in the source code for the custom control.

After you register to a control for a page, you can declare the control with a tag that looks like this:

Another option is to register the control in your website's configuration file. This is a new option in ASP.NET 2.0. If you want to register a control so that it can be used by all pages in an application, then you can add the following element to your Web.Config file:

I tend to use this second option the most often when incorporating custom controls into my applications.

Finally, you can add a custom control to the Visual Studio (or Visual Web Developer) Toolbox. If you add a control to the Toolbox, then you can add the control to a page simply by dragging the control from the Toolbox onto the page.

Unfortunately, you cannot take advantage of this last option when creating custom controls in the App_Code folder. You can add a custom control to the Toolbox only when the control has been compiled into a separate assembly. When we create the WhoIsLooking control later in this article, we will create the control as a separate assembly.

You add a control to the Toolbox by right-clicking the Toolbox window and selecting the menu option Choose Items. Selecting this menu item will open a dialog box that enables you to browse to an assembly (Click the Browse button). After you select the assembly that contains the custom control, the control will appear in your Toolbox.

Embedding Javascript

Our control is going to do something much more interesting than merely render some HTML to the browser. Our control is going to inject Javascript and CSS into its containing page.

There is one main class in the ASP.NET Framework included for working with Javascript: the ClientScriptManager class. This class is exposed by the Page.ClientScript property. The ClientScriptManager class has several useful methods for working with Javascript including:

RegisterClientScriptBlock() - Adds a script to a page right after the opening server-side
tag
RegisterStartupScript() - Adds a script to a page right before the closing server-side tag
RegisterClientScriptInclude() - Adds a reference to an external Javascript file
GetWebResourceUrl() - Returns the URL to a server-side resource

The RegisterClientScriptBlock and RegisterStartupScript methods enable you to add inline Javascript scripts to a page. If you have a little snippet of Javascript that you need to add to a page, then these are great methods to use. However, if you need to work with a more complex Javascript script, as we will need to do, then you should use either the RegisterClientScriptInclude() or GetWebResourceUrl() method.

The RegisterClientScriptInclude() method adds a tag that looks like this to your page:

The method simply adds a reference to an external Javascript file (you supply the method with the path to the Javascript file that you want to include).

The disadvantage of using the RegisterClientScriptInclude() method is that it requires you to distribute a separate Javascript file (or files) with your custom control. In order for people to use your control, they need to add the necessary Javascript files to their projects in the right locations.

A better alternative is to take advantage of the GetWebResourceUrl() method. You can embed a Javascript file (or any other type of resource) directly into your custom control. Using the GetWebResourceUrl() method, you can get the URL that you need to retrieve the embedded Javascript file from your control. In other words, by taking advantage of the GetWebResourceUrl() method, you can distribute a single assembly (.dll file) that contains both your custom control and Javascript files.

The tricky part is embedding the resource (the Javascript file) in the assembly. Unfortunately, you cannot embed a resource into an assembly when you create a control in the App_Code folder. You need to create the control in a separate project. For this reason, I created the custom WhoIsLooking control in a separate Class Library project.

You cannot create a Class Library project with Visual Web Developer. If you want to create a Class Library project, you either need to use the full version of Visual Studio 2005 or you need to download either Microsoft Visual C# 2005 Express Edition or Microsoft Visual Basic 2005 Express Edition from the Microsoft website (The download that accompanies this article includes both a Visual C# Express and Visual VB.NET Express Class Library project that contains the source code for the WhoIsLooking control).

Note: When creating custom controls in a Class Library project, you need to add a reference to the System.Web.dll assembly. Select Project, Add Reference and select the System.Web assembly from beneath the .NET tab.

Within Visual C# Express or Visual VB.NET Express, you can embed any file as a resource into an assembly by selecting the file in the Solution Explorer window, opening the Properties window, and changing the Build Action property for the file to the value Embedded Resource.

Next, you need to add a WebResource attribute to the AssemblyInfo file for each embedded resource. When working with Microsoft Visual Basic 2005 Express Edition, select the menu option Project, Show All Files and expand the My Project folder in the Solution Explorer window to view the AssemblyInfo file. When working with Microsoft C# 2005 Express Edition, expand the Properties folder to view the AssemblyInfo file. You need to add the following attribute to embed an image resource named MyImage.gif:

VB.NET

[Assembly: WebResource("ProjectNamespace.MyImage.gif", "image/gif")]

By default, the ProjectNamespace will be the same as your project name. In the case of the WhoIsLooking project, the project namespace is WhoIsLooking. You can view the default namespace for your project by right-clicking on the name of your project in the Solution Explorer window and selecting Properties.

The WhoIsLooking control adds a reference to Javascript file in its OnPreRender() method. The OnPreRender() method includes the following two lines of code:

// Add Javascript include

string scriptUrl = Page.ClientScript.GetWebResourceUrl( this.GetType(),

"WhoIsLooking.WhoIsLooking.js");

Page.ClientScript.RegisterClientScriptInclude("WhoIsLooking", scriptUrl);

VB.NET

' Add Javascript include

Dim scriptUrl As String = Page.ClientScript.GetWebResourceUrl(Me.GetType(), "WhoIsLooking.WhoIsLooking.js")

Page.ClientScript.RegisterClientScriptInclude("WhoIsLooking", scriptUrl)

Embedding Cascading Style Sheets

You can use the same technique that we used to embed Javascript into our custom control to embed a Cascading Style Sheet. The WhoIsLooking control takes advantage of a Cascading Style Sheet to format the appearance of the control.

If you select the WhoIsLooking.css file in the Solution Explorer window and view the properties for the file, then you will see that the Build Action for the file is set to the value Embedded Resource.

Furthermore, the WhoIsLooking project includes the following attribute in its AssemblyInfo file:

VB.NET

[Assembly: WebResource("WhoIsLooking.WhoIsLooking.css", "text/css")]

Finally, the WhoIsLooking control includes the following lines of code in its OnPreRender() method:

VB.NET

' Add style sheet to parent page

Dim cssUrl As String = Page.ClientScript.GetWebResourceUrl(Me.GetType(), "WhoIsLooking.WhoIsLooking.css")

Dim cssLink As New HtmlLink()

cssLink.Href = cssUrl

cssLink.Attributes.Add("rel", "stylesheet")

cssLink.Attributes.Add("type", "text/css")

Page.Header.Controls.Add(cssLink)

' Add class name

Me.CssClass = "WhoIsLooking"

// Add style sheet to parent page

string cssUrl = Page.ClientScript.GetWebResourceUrl(this.GetType(),

"WhoIsLooking.WhoIsLooking.css");

HtmlLink cssLink = new HtmlLink();

cssLink.Href = cssUrl;

cssLink.Attributes.Add("rel", "stylesheet");

cssLink.Attributes.Add("type", "text/css");

this.Page.Header.Controls.Add(cssLink);

// Add class name

this.CssClass = "WhoIsLooking";

This code grabs a reference to the external Cascading Style Sheet file by taking advantage of the GetWebResourceUrl() method. Next, an HtmlLink control is created and added to the header for the page. This control renders the following HTML:

Notice that the link refers to a strange file named WebResource.axd. Resources are exposed to the client-side through an HTTP handler named WebResource.axd. The link contains a long key that uniquely identifies the resource to retrieve.

Finally, the code associates the WhoIsLooking control with the WhoIsLooking Cascading Style Sheet class. Any style rules for the WhoIsLooking class are applied to the WhoIsLooking control automatically.

Using an external Cascading Style Sheet to format a control is great way to style a control when you need to provide a lot of default formatting. You can use the handy Style Sheet editor included in Visual Studio to build up a fancy Style Sheet and then embed it in your control.

Using Ajax

The WhoIsLooking control takes advantage of Ajax to display who is visiting a particular web page in real time. The control polls the server (by default, every 5 seconds) to retrieve a list of the people currently visiting the page.

Ajax stands for Asynchronous Javascript and XML. Ajax enables you to send information back and forth between a web browser and a web server without posting the page back to the web server. Communication happens behind the scenes.

The WhoIsLooking control takes advantage of the Ajax support built into the ASP.NET 2.0 Framework. In the ASP.NET 2.0 Framework, Ajax is called client callbacks. I'm going to continue to refer to the technology as Ajax instead of client callbacks because no one refers to the technology as client callbacks.

Implementing Ajax in a custom control requires you to complete three steps:

(1) Use the GetCallbackEventReference() method to initiate an Ajax call from the browser to the web server

(2) Implement the ICallBackEventHandler interface to respond to the Ajax call on the server-side. This interface has two methods that you must implement: the RaiseCallbackEvent() and GetCallbackResult methods.

(3) Create a Javascript function that does something with the result returned by the server

The WhoIsLooking control initiates an Ajax call every 5 seconds. The control includes the following code in its OnPreRender() method:

// Add polling call

string callback = Page.ClientScript.GetCallbackEventReference

(

this,

null,

"WhoIsLooking.UpdateDisplay",

String.Format("'{0}'", this.ClientID),

"WhoIsLooking.CallbackError",

true);

string startupScript = String.Format("setInterval( \"{0}\", {1} );", callback, _PollingInterval * 1000);

Page.ClientScript.RegisterStartupScript(this.GetType(), "WhoIsLooking", startupScript, true);

VB.NET

' Add polling call

Dim callback As String = Page.ClientScript.GetCallbackEventReference( _

Me, _

Nothing, _

"WhoIsLooking.UpdateDisplay", _

String.Format("'{0}'", Me.ClientID), _

"WhoIsLooking.CallbackError", _

True)

Dim startupScript As String = String.Format("setInterval( ""{0}"", {1} );", callback, _PollingInterval * 1000)

Page.ClientScript.RegisterStartupScript(Me.GetType(), "WhoIsLooking", startupScript, True)

In the first line of code, the GetCallbackEventReference() method is used to get the snippet of Javascript necessary for initiating the Ajax call. Next, the Javascript window.setInterval method is used to initiate the Ajax call whenever a particular interval of time passes (the default polling interval is 5 seconds). Finally, the RegisterStartupScript() method is used to add the Javascript to the page.

The WhoIsLooking control implements the ICallbackEventHandler interface. The control includes both a RaiseCallbackEvent() and GetCallbackResult() method. The RaiseCallbackEvent() method adds the current user to the list of users viewing the page. The method also removes users who have not viewed the page for more than 10 seconds (twice the polling interval).

The GetCallbackResult() method returns a list of users viewing the page back to the browser. The following information is returned for each user:

userId - Unique id for each user (the Session ID)
userName - The authenticated user name (otherwise, the value “anonymous”)
duration - The amount of time (in minutes) that the user has visited the page
browser - The type and version of the user's browser
remoteHost - The domain name of the user's host
platform - The operating system used by the remote browser

This method returns a string that represents a JSON array of users. JSON is the standard format for serializing information in an Ajax call (to learn more about JSON, visit JSON.org). For example, if there were two users visiting the page, the JSON string would look something like this:

[{userId:"fooglm45cjcycw55qi4yluvk",userName:"SUPEREXPERT\\Steve", duration:"0 minute(s)", browser: "IE 7.0", remoteHost: "superexpert.com", platform: "WinXP"},{userId:"1kqatn55sxc4vi55ummxghil",userName:"SUPEREXPERT\\Bill", duration:"0 minute(s)", browser: "Firefox 1.5.0.11", remoteHost: "superexpert.com", platform: "WinXP"}]

You create a JSON array by creating a comma-separated list of values enclosed in brackets. You create a JSON object by create a comma-separated list of name/value pairs enclosed in curly braces. That's pretty much it for the JSON standard (it's much leaner and easier to use than XML).

Finally, the WhoIsLooking control uses a Javascript function named UpdateDisplay() to display the list of users in the browser. This function creates a

tag for each user. When you hover your mouse over a

tag, details for the user popup (see Figure 2).

Figure 2 - Viewing the WhoIsLooking control

Retrieving User Information

Most of the information that the WhoIsLooking control retrieves for each user is retrieved with the help of the HttpBrowserCapabilities class (this class is exposed by the Request.Browser property). The HttpBrowserCapabilities class contains a wealth of information about the browser being used to visit the page. There are far too many properties to list here, but here is a random selection of some of the more interesting ones:

• AOL - Returns true if the client is using an AOL browser
• Browser - Returns the type of browser (IE, Firefox, Opera)
• ClrVersion - Returns the version of the .NET Framework installed on the client
• EcmaScriptVersion - Returns the version of Javascript installed on the client
• SupportsCallback - Returns a value indicating whether the browser supports client callbacks (Ajax)
• W3CDomVersion - Returns the version of the DOM (Document Object Model) supported by the browser

There is one property that the WhoIsLooking control displays that it does not get with the help of the HttpBrowserCapabilities class. The control displays the remote domain name associated with the user requesting the page. The remote domain name is retrieved by performing a reverse DNS lookup. In the .NET Framework 2.0, performing a reverse DNS lookup is ridiculously easy. The WhoIsLooking control uses the following code:

// Get remote IP address

_remoteIP = context.Request.UserHostAddress;

// Get host name

_remoteHost = Dns.GetHostEntry(_remoteIP).HostName;

VB.NET

' Get remote IP address

_remoteIP = context.Request.UserHostAddress

' Get host name

_remoteHost = Dns.GetHostEntry(_remoteIP).HostName

Conclusion

I think the WhoIsLooking control is super cool. The control takes advantage of Javascript and Ajax to display a list of everyone who is looking at a particular Web page in real time. Please feel free to add the control to your websites, I'll come and visit.

Creating a Vanity Search Page

Stephen Walther — Sat, 10 Mar 2007 20:09:12 GMT

	It's all about you. Learn how to call the Windows Live Search service to create a vanity page that displays images, news articles, and websites about you.
Stephen Walther Superexpert Blog Difficulty: Easy Time Required: Less than 1 hour Cost: Free Software: Visual Web Developer 2005 Express Edition

This month, we create a vanity search page. The vanity search page displays any images, news or website entries about a particular person (for example, you). To create this page, we take advantage of the Windows Live Search API. This free API enables you to retrieve search results by calling a web service that Microsoft exposes on the web.

I decided to write this article because I wanted an excuse to play with the Windows Live SDK (see http://dev.live.com). The SDK includes documentation and samples for accessing all of the Windows Live web services including the Windows Live Search Web Service, Virtual Earth, and Windows Live Alerts.

I fully admit that I was actively avoiding writing this article because I dreaded the thought of needing to learn yet another Application Programming Interface. I was pleasantly surprised to discover that the API for Windows Live Search is both logical and painlessly simple to understand. I wrote the code for this article in less than an hour.

Before you can access the Windows Live services, you need to get an Application ID. You pass this ID to the Windows Live services to identify yourself. You get an Application ID by signing an agreement at the following URL: http://search.msn.com/developer/appids.aspx.

Figure 1 - Adding a Web Reference for Windows Live Search

After you have an Application ID, you are ready to start calling Windows Live web services. Here are the steps for creating the vanity search page:

1. Launch Visual Web Developer and create a new Web Site

2. Select the menu option Website, Add Web Reference to add a Web Reference to the Windows Live Search web service (see Figure 1). Enter the following address into the URL field: http://soap.search.msn.com/webservices.asmx?wsdl. When you click OK, a new Web reference named com.msn.search.soap is created.

3. Create a new Web Form Page by selecting the menu option Website, Add New Item. When you create the new Web Form Page, give it the name Vanity.aspx. Also, make sure that the checkbox labeled Place code in separate file is not checked.

4. Replace the contents of the page with the following code:

VB.NET Code

<%@ Page Language="VB" %>

<%@ Import Namespace="com.msn.search.soap" %>

<%@ Import Namespace="System.Text.RegularExpressions" %>

PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



"http://www.w3.org/1999/xhtml" >

"server">

Untitled Page







"form1" runat="server">



"lstResponses"

Runat="server">



<%# Eval("Source") %> (<%# Eval("Total") %> Results)

"grdResults"

DataSource='<%# Eval("Results") %>'

Runat="server">











"lnkResult"

ImageUrl='<%# toImage( Eval("Image")) %>'

Text='<%# hiLite( Eval("Title") ) %>'

NavigateUrl='<%# Eval("Url") %>'

Runat="server" />



<%# hiLite( Eval("Description") ) %>

C# Code

<%@ Page Language="C#" %>

<%@ Import Namespace="com.msn.search.soap" %>

<%@ Import Namespace="System.Text.RegularExpressions" %>

"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



"http://www.w3.org/1999/xhtml" >

"server">

Vanity Search







"form1" runat="server">



"lstResponses"

Runat="server">



<%# Eval("Source") %> (<%# Eval("Total") %> Results)

"grdResults"

DataSource='<%# Eval("Results") %>'

Runat="server">











"lnkResult"

ImageUrl='<%# toImage( Eval("Image")) %>'

Text='<%# hiLite( Eval("Title") ) %>'

NavigateUrl='<%# Eval("Url") %>'

Runat="server" />



<%# hiLite( Eval("Description") ) %>

Before you use the vanity search page, you should modify two of the constants that appear at the top of the page: the appId and query constants. Assign the App ID that you get from visiting the following URL to the appId constant: http://search.msn.com/developer/appids.aspx. Enter anything you want for the query constant. In the page above, the name Bill Gates (enclosed in quotes) is assigned to the query constant. When you open the page in a web browser, you should see a page similar to Figure 2.

Figure 2 - Image results for Bill Gates vanity search page

The page displays three different groups of results. First, the page displays a list of images that match the search query. Next, the page displays a list of news articles. Finally, the page displays a list of websites (see Figure 3).

Figure 3 - Web results for Bill Gates vanity search page

The Windows Live Search web service currently supports the following types of searches:

Image - Returns a list of images that match the search query.
Inline Answers - Only available for commercial use. This type of search returns information from Encarta, Finance, Weather, and Movie show times.
News - Returns results from online news sources.
Phone Book - Returns results from white and yellow page phone books.
Query Location - Returns latitude and longitude information associated with a query.
Spelling - Returns a list of spelling suggestions.
Web - Returns a list of websites that match the search query.

You perform a search by creating an instance of the SearchRequest class. You assign the text of your search query to the SearchRequest class's Query property. This class also includes a Requests collection. You add one or more SourceRequest objects to this collection that represent different types of searches (Image, Web, News, and so on). After you get all of the objects ready, you call the MSNSearchService.Search() method to actually perform the search.

The search results are displayed with the help of a DataList and Repeater control. The DataList displays the source of the search and the number of results for each source returned. The Repeater control is nested in the DataList and it displays the actual search results.

Conclusion

As I mentioned before, I wrote this article as an excuse to play with the Windows Live SDK. I am very happy that I got the chance to experiment with this SDK since I discovered that it is very easy to work with. I'm looking forward to trying out some of the other Windows Live services such as the Virtual Earth and Alerts services over the coming months.

Creating an ASP.NET Hangman Control

Stephen Walther — Sun, 25 Feb 2007 04:50:59 GMT

	In this post, Stephen Walther shows you how to create an ASP.NET Hangman control. This control contains embedded images, sounds, XML, and Javascript.
Stephen Walther Steve's Blog Difficulty: Easy Time Required: Less than 1 hour Cost: Free Software: Visual Basic or Visual C# Express Editions,Visual Web Developer Express, Hardware: Download: Download

This month, we create an ASP.NET Hangman control. Our control will render all of the necessary images, sounds, and scripts to create a richly interactive hangman game (see Figure 1). Our control will work with the most recent versions of Microsoft Internet Explorer, Mozilla Firefox, and Opera.

We tackle several advanced features of the ASP.NET 2.0 framework in this article. You learn how to build custom controls that take advantage of Javascript. You also learn how to embed resources such as images, sound, and XML in an assembly. Finally, you learn how to write cross-browser compatible Javascript.

Using the Hangman Control

If you are anxious to start playing hangman, you can download the ZIP file that accompanies this article. Click the Download link above. The ZIP file contains two projects: the Visual Basic and the C# versions of the Hangman control. If you are interested in viewing or modifying the source code for the Hangman control, you can open the Visual Basic version with Microsoft Visual Basic 2005 Express Edition and the C# version with Microsoft C# 2005 Express Edition.

Here's how you use the Hangman control. Launch Visual Web Developer 2005 Express Edition and create a new website (select the menu option File, New Web Site). Next, add the control to your Toolbox by right-clicking beneath the General tab on your Toolbox and selecting the option Choose Items (see Figure 2). You must have a Web Form Page open in order to modify the Toolbox.

Next, under the .NET Framework Components tab, click the Browse button and browse to the Hangman assembly (dll file). There is both a VB.NET and C# version of this file (it doesn't matter which version you use since you can use a control written in C# with a VB.NET website and a control written in VB.NET with a C# website). The files are located in the following subfolders:

VB\Hangman\bin\Release\Hangman.dll

CS\Hangman\bin\Release\Hangman.dll

Click OK a couple of times to close the dialog boxes and the Hangman control should now appear on your Toolbox.

After you have added to the Hangman control to your Toolbox, you can add the control to any page simply by dragging the control onto a Web Form Page in either Design or Source view. That's all there is to adding this control to a page.

The Hangman control includes a default set of words included in an embedded XML file (these words are intended to be hard). If you prefer, you can associate a custom list of words with the Hangman control by assigning the path of an XML file to the control's WordsUrl property. The XML file should have the following format:

baby

easy

The file can contain as many words as you please.

Creating a Custom Web Control

The Hangman control is implemented as a custom ASP.NET Web Control. In other words, the control is a class that derives from the base System.Web.UI.WebControls.WebControl class. The Hangman class overrides one method of the base class: the OnPreRender() method.

The Hangman control's OnPreRender() method loads the XML, Javascript, sound, and image files. All of these resources are loaded by using the Page.ClientScript.GetWebResourceUrl() method to retrieve a valid URL for the embedded resource.

Embedding Images, Sounds, XML, and Javascript

The Hangman control includes embedded image, sound, XML, and Javascript files. These resources are embedded in the same assembly (dll) as the control so that the control can be distributed with a single assembly.

There are three steps required for embedding a resource in an assembly:

1) Set the Build Action for the resource to the value Embedded Resource. You set the Build Action for a file by selecting the file, opening the Properties Window, and modifying the Build Action property.

2) Add a WebResource attribute to the AssemblyInfo file for each embedded resource. When working with Microsoft Visual Basic 2005 Express Edition, select the menu option Project, Show All Files and expand the My Project folder in the Solution Explorer Window to view the AssemblyInfo file. When working with Microsoft C# 2005 Express Edition, expand the Properties folder to view the AssemblyInfo file. You need to add the following attribute to embed an image resource named MyImage.gif:

VB.NET

[Assembly: WebResource("ProjectNamespace.MyImage.gif", "image/gif")]

By default, the ProjectNamespace will be the same as your project name. In the case of the Hangman project, the project namespace is Hangman.

3) Finally, in your code, you can retrieve a URL to an embedded resource by using the Page.ClientScript.GetWebResourceUrl() method. This method accepts two parameters: a type and a parameter name. Typically, you will pass the type of the current class and the name of the embedded resource. For example, you would use the following line of code to get the URL to an image named MyImage.gif located in the Hangman project:

VB.NET

Dim imageUrl As String = Page.ClientScript.GetWebResourceUrl( this.GetType(), “Hangman.MyImage.gif”)

string imageUrl = Page.ClientScript.GetWebResourceUrl( me.GetType(), “Hangman.MyImage.gif”);

Be aware that all resource names are case-sensitive -- even in the case of VB.NET. Make sure that you refer to the name of the resource in the same way with the file name, attribute, and GetWebResourceUrl() method.

Cross-Browser Javascript

All of the logic of the Hangman game is implemented in the Hangman.js Javascript file. When the control loads, the Javascript initializeGame() function is called and all of the game elements are created.

When you click a letter, the selectLetter() function is called. If a matching letter is found, the display of matching letters is updated. If a matching letter is not found, the badGuessCount variable is updated and the image of the hangman is updated as well.

If you win a game, the doWin() function is called and if you lose a game the doLose() function is called. Both functions play a sound and both functions display a link that enables you to restart the game.

All of the Javascript was written in a cross-browser compatible way. The Javascript code works with Microsoft Internet Explorer, Mozilla Firefox, and Opera. Therefore, the Hangman control works with all three browsers.

Conclusion

The biggest hurdle that I encountered while writing this control was getting the embedded resources to work. Once I resolved the namespace issues and got all of the case-sensitivity issues under control, everything worked out. I was very happy that I was able to get all of the resource (including the XML file with the list of words) embedded into one control.

Creating Loud Websites

Stephen Walther — Thu, 25 Jan 2007 01:40:43 GMT

	In this post, Stephen Walther explains how to make your websites have more noise. You learn how to use Javascript to add sound effects to your ASP.NET pages.
Stephen Walther Steve's Blog Difficulty: Easy Time Required: Less than 1 hour Cost: Free Software: Visual Web Developer 2005 Express

I want to create noisy websites. All of our desktop applications make sounds. It seems completely unfair that our websites are so quiet.

For example, when you empty your computer's recycle bin your computer makes the satisfying sound of trash being dumped from a trash can. When you leave the desktop and enter the web, however, the world goes silent (almost like you are under water).

When you browse a catalog of products displayed on a website, each product should demand to be bought. When you hover your mouse over a picture of a music box, it should play a quiet tune. When you hover your mouse over a picture of a vacuum cleaner, it should make a mighty rrrrrrrrrrrrr sound.

Whenever I reveal my secret ambition to make noisy websites, people always groan. Everyone always thinks of all of those MySpace pages with the endlessly looping background music. But I don't mean background music, I mean noise.

We interact with websites through metaphors. We work with “files” and “folders” on a “desktop”. We grab files and “drag” them to new folders. Under the covers, of course, we are really just flipping massive numbers of bits. But, we understand our complex interactions with our computers by projecting metaphors that we've stolen from the physical world onto our machines.

The more closely our software interactions match our metaphors, the more satisfying the experience becomes. Dropping a file in a recycle bin to delete it makes perfect sense. If the recycle bin looks like a prototypical recycle bin, the experience seems more real. If the trash makes a satisfying trash-being-emptied sound, the experience is even more real.

In this month's post, I'm going to tackle the problem of adding sounds to your ASP.NET websites. The goal is to produce sounds dynamically using Javascript.

Methods of Making Sounds

Let's start with a quick review of the methods of generating sounds in a web page. There are three tags that you can add to a page to generate a sound: the tag, the tag, and the tag.

Here's how you add sound with the tag:

The tag is the tag that gave sound a bad name. This is the tag that everyone adds to their websites to create the endlessly looping background music.

The tag was introduced into the world (in the same month) with the release of Microsoft Internet Explorer 2.0 and Mosaic 2.1. Opera supports the tag, but Firefox does not.

Since the was never incorporated into any web standards (you won't find any mention of the tag in either the HTML or XHTML standards), most web authors avoid this tag as outdated and dead. Typically, you are encouraged not to use the tag in favor of either the or tag.

However, I use the sound tag in the Javascript that I develop at the end of this post. There is one very important advantage of the tag. The tag does not cause the information bar to popup in Internet Explorer when you use this tag in a page.

The Internet Explorer version of this tag has four important properties:

Balance -- Enables you to specify the balance between the left and right speaker
Loop -- Enables you to specify the number of times that the sound will repeat. The value -1 means loop infinitely
Src -- Enables you to specify the URL to the sound file
Volume -- Enables you to specify the volume of the sound (valid values range from -10,000 to 0)

As an alternative to the tag, you can use the tag. The tag was introduced to the world with the release of Netscape 1.1. The tag is now supported by all modern browsers.

Here's how you use the tag:

The src attribute points to the sound file and the type attribute specifies the MIME type of the file. Notice that the MIME type of a .wav sound file is indicated with the MIME type audio/x-wav. The x means that .wav is a custom type. Using the x is necessary because the .wav sound file format does not have a registered MIME type at IANA.

The tag is not limited to sounds. You can use the tag to embed a variety of different types of objects in a page including videos and pictures.

There's no master list of valid attributes for the tag. Different types of objects that you embed in a document will support different attributes. For example, on my computer, Windows Media Player is mapped to the .wav extension. Therefore, I can use Windows Media Player attributes with the tag.

One problem with using the tag is that you must have an application mapped to the type of file being downloaded. Unfortunately, on my computer, there was no application mapped to the .wav extension by default. When I initially requested a page that contained an embedded .wav file, I got the Internet Explorer information bar.

Since I don't want to inflict the Internet Explorer information bar on users when playing sounds, I don't use the tag in the Javascript at the end of this article. The element enables us to play .wav files without displaying the information bar.

The final -- and generally recommended -- method of adding sound to a web page is to use the tag. The tag is very similar to the tag. It allows you to embed objects in a page like this:

Notice that the tag uses the data attribute and not the src attribute to point to a file.

The difference between the tag and the tag is that the latter tag is supported by W3C web standards. If creating standards compliant websites is important to you, then you should use this tag.

Just like in the case of the tag, there is no master list of attributes for the tag. The list of valid attributes all depends on the application or plug-in being used to display the embedded object.

Unfortunately, when used with Internet Explorer, the tag causes the Internet Explorer information bar to popup just like the tag. In the Javascript at the end of this article, I use the tag for Internet Explorer and the tag for every other browser.

Generating Sounds with Javascript

So now that we've finished reviewing the possible methods of generating sound in a page, we are ready to create our Javascript that we'll use in our ASP.NET pages to generate sound. Our script will works with recent versions of all major browsers including Internet Explorer, Firefox, and Opera.

Since the script is small, the entire content of the PlaySound.js Javascript file is included right here:

PlaySound.js

if (window.attachEvent)
    window.attachEvent("onload", setupPlaySound);
else
    window.addEventListener("load", setupPlaySound, false); 


function setupPlaySound()
{
    if (navigator.appName == "Microsoft Internet Explorer")
    {
        var snd = document.createElement("bgsound");
        document.getElementsByTagName("body")[0].appendChild(snd);
        
        playSound = function(url)
        {
        
            snd.src = url;
        }
    }
    else
    {
        playSound = function(url)
        {
            var obj = document.createElement("object");
            obj.width="0px";
            obj.height="0px";
            obj.type = "audio/x-wav";
            obj.data = url;
            
            var body = document.getElementsByTagName("body")[0];
            body.appendChild(obj);
        }
    }
}

The first lines of the Javascript create an event handler for the browser window load event. Internet Explorer uses the attachEvent() method to create an event handler and other browsers use the addEventListener() method.

The setupPlaySounds() method is called after the window is loaded. This method creates the playSound() method. Javascript enables you to conditionally create different versions of a function. There is one version of the playSound() method that is created in the case of Internet Explorer and another version that is created in the case of every other browser.

The Internet Explorer version of the playSound() method takes advantage of the tag to play a sound. The alternative playSound() method takes advantage of the tag.

If you link the Javascript file above into an ASP.NET page, then you can play a sound by calling the playSound() method and passing the URL of a sound file. You can link the PlaySound.js file to an ASP.NET page by adding the following tag to the page:

And, adding the following link to a page will cause the sound file ClickHere.wav to play whenever you hover your mouse over the link.

Click Here!

The playSound() method works with recent versions of Internet Explorer, Firefox, and Opera.

I did run into one issue when testing this method with Firefox. Firefox uses the Apple QuickTime plug-in to play sound files. However, on my computer, QuickTime was not mapped to .wav files. I fixed this problem by launching the QuickTime Player, and selecting the menu option Edit, Preferences, QuickTime Preferences and selecting the File Types tab. Under this tab, I was able to associate .wav files with the QuickTime Player.

Conclusion

I think the web would be a much more enjoyable place if it were only a little louder. In this post, I've provided you with a cross-browser compatible Javascript playSound() method that you can use in your ASP.NET pages to add sound. Please make some noise.

Displaying Gentle Error Messages with ASP.NET

Stephen Walther — Fri, 29 Dec 2006 03:51:52 GMT

	Learn how to display gentler error messages when errors are encountered while developing ASP.NET applications. In this article, Stephen Walther shows you how you can modify the default ASP.NET error page so that it displays motivational sounds, messages, and pictures.
Stephen Walther Stephen's Blog Difficulty: Easy Time Required: Less than 1 hour Cost: Free Software: Visual Web Developer 2005 Express Edition Hardware: Download: Download

I fly out to companies and teach workshops on building ASP.NET applications to developers new to the ASP.NET framework. Typically a developer starts out excited to learn something new. Unfortunately, a developer's first experience of the ASP.NET framework is often the error page -- the angry page with the yellow background and the red error message.

When a novice developer encounters their first error message, I try to be reassuring. I explain that errors are normal and good and that an ASP.NET developer will view the error page at least half a billion times while developing a project of any reasonable complexity. After all, the mark of a good development framework is that it throws a lot of errors at you. A framework that throws a lot of errors prevents you from doing something stupid and deploying a buggy application into production.

However, the question remains: why does the ASP.NET Framework seem so angry? Why the harsh yellow background and bold red error messages (see Figure 1)? Why can't the error page be more gentle? In other words, why can't the error page be more Myst than Halo?

Figure 1 -- Angry ASP.NET Error Page

This question brings us to the topic of this article. The nice thing about the ASP.NET Framework is that you can customize just about any aspect of the framework in any way that you want. This month's project is to build a friendlier, gentler ASP.NET error page. Our error page will use nurturing colors such as blues and grays instead of yellows and reds. Furthermore, our custom error page will randomly display different motivational messages and pictures and play different soothing background sounds.

The Visual Studio Installer file that accompanies this article includes a new VB.NET and C# Project Template named Friendly Errors. If you choose this template when creating a new project, the default error message page will be replaced with a custom error message page (see Figure 2).

Figure 2 -- Gentle ASP.NET Error Page

Handling Application Exceptions

I should admit up front that I thought that this would be an extremely easy project. The ASP.NET Framework enables you to easily create a custom error page by adding a section to your application's Web configuration (Web.config) file. For example, adding the following Web.config file to the root of your application causes a page named CustomError.aspx to be displayed when there is any error:

Adding this configuration file to your application works great. Whenever there is an error, the user is redirected to the CustomError.aspx page automatically. You can display any message in this page that you want. For example, you can display the message “This site is currently undergoing scheduled maintenance”.

Unfortunately, however, there is no way in the CustomError.aspx page to get information about the error that caused the redirect to the CustomError.aspx page. You can display a message, but you cannot display detailed error information.

Therefore, in this project, I took another approach. Instead of using the section, I handled the Application Error event. This event is raised whenever there is any unhandled exception in an application. In other words, if any code within a page or a component raises an exception, and the code is not wrapped by a Try...Catch block, then the Application Error event is raised.

There are two ways that you can handle the Application Error event. You can handle the event in the Global.asax file or you can handle the event by creating a custom HTTP Module. I handled the Application Error event in a module named FriendlyErrorsModule. The code for the FriendlyErrorsModule is contained in Listing 1.

Listing 1 -- FriendlyErrorModule.cs

using System; 

using System.Web; 

using System.Web.Configuration; 

namespace Superexpert 

{ 

///  

/// Handles all unhanlded exceptions in an application 

/// 
 

public class FriendlyErrorsModule : IHttpModule 

{ 

  public void Init(HttpApplication app) 

  { 

    app.Error += new EventHandler(app_Error); 

  } 

  ///  

  /// When debug mode is enabled, display 

  /// friendly error page 

  /// 
 

  void app_Error(object sender, EventArgs e) 

  { 

    HttpApplication app = (HttpApplication)sender; 

    HttpContext context = app.Context; 

    Exception error = context.Server.GetLastError().GetBaseException(); 

    context.Response.Clear(); 

    CompilationSection compilationConfig = (CompilationSection)WebConfigurationManager.GetWebApplicationSection("system.web/compilation"); 

    if (compilationConfig.Debug) 

      context.Server.Transfer("~/FriendlyErrors/Debug.aspx"); 

    else 

      context.Server.Transfer("~/FriendlyErrors/Public.aspx"); 

  } 

  public void Dispose() 

  { 

  } 

} 

}

Listing 1 -- FriendlyErrorModule.vb

Imports System 

Imports System.Web 

Imports System.Web.Configuration 

Namespace Superexpert 

'''  

''' Handles all unhanlded exceptions in an application 

''' 
 

Public Class FriendlyErrorsModule 

Implements IHttpModule 

  Public Sub Init(ByVal app As HttpApplication) Implements IHttpModule.Init 

    AddHandler app.Error, AddressOf app_Error 

  End Sub 

  '''  

  ''' When debug mode is enabled, display 

  ''' friendly error page 

  ''' 
 

  Sub app_Error(ByVal sender As Object, ByVal e As EventArgs) 

    Dim app As HttpApplication = CType(sender, HttpApplication) 

    Dim context As HttpContext = app.Context 

    context.Response.Clear() 

    Dim compilationConfig As CompilationSection = CType(WebConfigurationManager.GetWebApplicationSection("system.web/compilation"), CompilationSection) 

    If (compilationConfig.Debug) Then 

      context.Server.Transfer("~/FriendlyErrors/Debug.aspx") 

    Else 

      context.Server.Transfer("~/FriendlyErrors/Public.aspx") 

    End If 

  End Sub 

  Public Sub Dispose() Implements IHttpModule.Dispose 

  End Sub 

End Class 

End Namespace

The class in Listing 1 implements the IHttpModule interface. This interface has two methods that you must implement: Init() and Dispose(). In Listing 1, the Init() method is used to wire the Application Error event to a handler named app_Error.

The app_Error handler checks whether debugging is enabled in the Web.config file. If debugging is enabled, then the user is transferred to a page named Debug.aspx whenever there is an error. Otherwise, if debugging is not enabled, the user is transferred to a page named Public.aspx.

Creating a Custom Error Page

The last part of this project involved creating the error page itself. The custom error page is named Debug.aspx. This page does a number of different things.

First, the page displays detailed error information. To get detailed error information, you must create an instance of the System.Diagnostics.StackTrace class. You can take advantage of the StackTrace class to get the name of the page associated with the error as well as the source code that caused the error.

The Friendly Errors Project Template includes a class named FriendlyError. This class includes methods for retrieving detailed error information. the Debug.aspx page uses the FriendlyError class behind the scenes.

The Debug.aspx page also displays a random picture. You can modify the pictures that the Debug.aspx page displays by modifying the contents of the FriendlyErrors/Pictures folder. The Debug.aspx page randomly displays one picture from this folder.

You can add any pictures to this folder that you want. For example, you can add baby pictures and motivational pictures of your favorite foods or persons.

The Debug.aspx page also displays a random motivational message. You can modify the motivational messages displayed by the Debug.aspx page by modifying the FriendlyErrors/Messages/Messages.xml file. This XML file contains a list of elements that contain each of the motivational messages.

Finally, the Debug.aspx page plays a background sound. The page uses the tag so that the background sound will play correctly in both Microsoft Internet Explorer and Mozilla Firefox. You can customize the background sounds used by the Debug.aspx page by modifying the contents of the FriendlyErrors/Sounds folder. The Debug.aspx page randomly plays a sound from this folder.

Again, you can add any sound file to this folder that you please. By default, the folder contains soothing chime sounds. If you want, you could add drop other motivational sounds into this folder such as Homer Simpson saying Doh!

Testing the Custom Error Page

You'll see the custom error page, Debug.aspx, whenever there is any unhandled exception in your project. Don't worry, unless you are the perfect programmer, you'll see the Debug.aspx pretty quickly when developing an application when using the Friendly Errors Project Template.

If you insist on intentionally creating an error in your application, then you can use the page in Listing 2. Both the C# and VB.NET versions of this page cause an exception that causes the Debug.aspx page to be displayed.

Listing 2 -- BadPage.aspx (C#)

<%@ Page Language="C#" %> 

"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 

 

"http://www.w3.org/1999/xhtml" > 

"server"> 

Bad Page 

 

 

"form1" runat="server"> 

 

I am a bad page

Listing 2 -- BadPage.aspx (VB.NET)

<%@ Page Language="VB" %> 

PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 

 

"http://www.w3.org/1999/xhtml" > 

"server"> 

Bad Page 

 

 

"form1" runat="server"> 

 

I am a bad page

Conclusion

The purpose of this month's column is to demonstrate that you can customize just about any aspect of the ASP.NET Framework: including the default error page. If you are going to spend countless hours staring at one particular page (and I've spent an embarrassing number of hours of my life staring at the error page) then you might as well make the experience pleasant.