NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Exception Class

Represents the class that provides information required to handle and process errors.

Object
   Exception

[Visual Basic]
Public Class Exception
   Implements ISerializable
[C#]
public class Exception : ISerializable
[C++]
public __gc class Exception : public ISerializable
[JScript]
public class Exception implements ISerializable

Remarks

The Exception class is the base class from which all runtime exceptions inherit. Exceptions are objects that result from abnormal conditions that arise while a program executes.

An object cannot be "thrown" or "caught" unless it inherits from Exception. Most of the classes that inherit from Exception do not implement additional members or provide additional functionality; they simply inherit from Exception. It is the hierarchy of the exception classes, their names, and the information they carry which allows the exceptional conditions to be handled and execution of the code to continue.

The StackTrace property of Exception carries a stack trace that is invaluable for determining where the error occurred. But exceptions carry more information than this; we will discuss in the following paragraphs.

To improve the caller's ability to determine the reason an exception is thrown, it is desirable at times for a method to catch an exception thrown by a helper routine and, then to throw an exception more indicative of the error that has occurred. A new and more meaningful exception can be created, where the inner exception reference can be set to the original exception. This more meaningful exception can be thrown to the caller. Note that with this functionality, it is possible to create a series of linked exceptions that terminates with the exception that was first thrown.

The InnerException property can be used to create and preserve a series of exceptions during exception handling. It can be very helpful for the developer to create a new exception that catches the exception(s) thrown by prior exception(s). The original exception can be captured by the second exception in the InnerException property and provides the code that handles the second exception with additional information that can be used to handle the error appropriately. For example, suppose you have a function that reads a file and formats the data that it reads. The code tries to read from the file, but a FileException is thown. The function catches the FileException and throws a BadFormatException. In this case, the FileException could be saved in the InnerException property of the BadFormatException, enabling the code that catches the BadFormatException to examine the InnerException to discover what caused the initial error.

Exception objects also carry a message that provides details concerning the cause of an exception. This is represented by the Message property. To simplify the task of localization, the message strings carried by the exceptions thrown by the base class library exist in resource files. At run time, a localized message is retrieved by name from the resource file associated with the user's default settings (see the code sample below). Developers are encouraged to use the localized message texts available in the resource files with the base name "mscorlib". This will allow developers to forego the expense of localizing resources, although the messages in these files may not work in every situation. A resource manager for these files is accessible via ResourceManager. There is also a code sample in the reference page for System.ResourceReader that displays the contents of the mscorlib.resources file.

Note: Currently the message strings used by the base class library are in US English (en-us) only, and are stored in the file mscorlib.resources. After this file has been localized, there will be a resource file for each culture: mscorlib_en-us.resources, mscorlib_jpn.resources, mscorlib_de.resources, mscorlib_zh.resources, etc. For details on localized resources, see the Resources in TBD specification and the TBD API.

Finally, to provide the user with extensive information concerning why the exception occurred, the HelpLink property can hold a URL (or URN) to a help file.

Many traditional error-handling systems use pre-defined return values to handle errors. This approach has a couple of downsides.

For interoperability between legacy systems and the NGWS runtime, every exception has an System.Exception.ErrorCode property that stores by default the associated HRESULT, an integer value that identifies the error that has occurred and is used in COM.

A SetErrorCode method is provided (see the description of this member for the reasoning behind providing a read-only property and set method), allowing the default value to be changed.

The runtime provides a more functional error handling system. Blocks of code may be wrapped in a try block. When an exception occurs in that block, control is passed to a catch block that may be specific to a particular exception or general to a class of exceptions. The exception is passed up the call stack until a handler is found for it. If no handler can be found, the runtime's handler displays the exception name, message and a full stack trace from where it was thrown.

Requirements

Namespace: System

Assembly: mscorlib.dll

Example

The following Managed C++ example demonstrates how resource files are used in order to localize the messages carried by exceptions.

#import <mscorlib.dll>
using namespace Resources;
 
[managed] class Customers
{
 
public:
    // The ResourceManager for the
mscorlib.resources file.
    static ResourceManager
*rm = Assembly::SystemResMgr;
  
    static int _maxIndex =
100;
 
    /**
     * This method returns
the string at the specified index.
     * The index must be
greater than 0 and less than _maxIndex,
     * otherwise an
exception is thrown. The message to be
     * carried by the
exception is obtained from the
     * mscorlib.resources
file.
     */
 
    static String *
GetName (int index)
    {
   if (index < 0 ||
index > _maxIndex)
       {
       String *paramName =
L"index";
 
       //Here we use the
message string identified as ArgumentOutOfRange_ActualValue
       //in the
mscorlib.resources file.
       String *message =
String::Format (rm->GetString (L"ArgumentOutOfRange_ActualValue"),
Int32::Box(index));
 
       throw new
ArgumentOutOfRangeException (paramName, Int32::Box(index), message);
       } 
// do some work here...
 
   return
L"done";
    }
};
 
void main ()
{
    // Call GetName with
an invalid index.
    try
    {
       Customers::GetName
(-3);
    }
   
catch(ArgumentOutOfRangeException *e)
    {
       
Console::WriteLine(L"Caught:
ArgumentOutOfRangeException\r\n\t{0}", e->Message);
   }
  
    /**
     * OUTPUT:
     *
     * Caught: ArgumentOutOfRangeException
     *         Actual value was -3
     */
 
};

See Also

Exception Members | System Namespace