The ASP.NET AJAX Script Library includes several useful classes with respect to debugging and testing, including the Error and Sys.Debug classes. The Error class extends the native JavaScript Error object and allows more specific error objects and messages to be created for a given error. It is used extensively throughout the ASP.NET AJAX Library debug scripts to test that the correct number of parameters are passed to functions, passed parameter types match up with the expected types, types aren't undefined, functions are fully implemented, and much more. The Error class is used sparingly in the release version of the ASP.NET AJAX Library scripts so that file sizes are minimized as much as possible.
The Error class has several different functions that can be used to create specific types of errors. The majority of the functions that can be called to create error objects relate specifically to function parameters, but others exist that are used by classes such as the PageRequestManager class. All of the Error class's available functions are shown in the following table.
You can use the Error object to raise specific types of errors when invalid parameters are passed to a function, when calls are made to functions that aren't fully implemented, or when you need to ensure that the correct line number and filename show up when errors are raised.
Listing 15-5 shows an example of using the Error object's argumentType, popStackFrame, and notImplemented functions with a custom script that defines an Album class.
Wrox.ASPAJAX.Samples.Album.prototype = { //Additional code removed for brevity addSong: function(song) { /// <value type="Wrox.ASPAJAX.Samples.Song"></value> if (Object.getTypeName(song) != 'Wrox.ASPAJAX.Samples.Song') { var e = Error.argumentType('song', Object.getType(song), Wrox.ASPAJAX.Samples.Song,"Wrox.ASPAJAX.Samples.Song required!"); e.popStackFrame(); throw e; } Array.add(this._songs,song); }, rateSong: function(song,rating) { throw Error.notImplemented("rateSong() has not yet been implemented"); } //Additional code removed for brevity } |
The first use of the Error object is in the definition for the addSong function in Listing 15-5. This function accepts a Wrox.ASPAJAX.Samples.Song object as a parameter. If a Song parameter type is not passed, a call is made to the Error.argumentType function to create a Sys.ArgumentTypeException error object. This function accepts the name of the parameter in error (song in this example), the actual parameter type passed, the expected parameter type, and the error message that should be shown to the caller. Once the Error object is created, a call is made to popStackFrame to ensure that the line number and filename are properly reported to the caller. In some browsers, the line number is reported at the location that the error was created rather than the location where it was actually thrown. The popStackFrame function remedies this problem and ensures that the line number and filename are reported correctly.
The Error object is also used in the definition for the rateSong function in Listing 15-5. Because this function is not yet implemented, a call is made to the Error.notImplemented function, and the error message that the caller should see is passed as a parameter. Listing 15-6 shows calls to the Album class's addSong and rateSong methods and demonstrates how to catch returned errors.
function RateSong() { var album = new Wrox.ASPAJAX.Samples.Album(); var song = new Wrox.ASPAJAX.Samples.Song(3,$get("txtSong")); try { //Should pass song object here but demonstrate using Error object in Album //to verify proper parameter type is passed album.addSong(album); } catch(e) { alert(e.message); } try { //rateSong() not implemented album.rateSong(song,$get("txtSongRating")); alert("Song rated!"); } catch(e) { alert(e.message); } } |
Now that you've seen how the ASP.NET AJAX Script Library's Error class can be used, let's take a look at the Sys.Debug class and see how it can be used to write error messages and identify the reason they occurred.