Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Exception.Data Property

Gets a collection of key/value pairs that provide additional user-defined information about the exception.

Namespace: System
Assembly: mscorlib (in mscorlib.dll)

public:
virtual property IDictionary^ Data {
	IDictionary^ get ();
}
/** @property */
public IDictionary get_Data ()

public function get Data () : IDictionary

Not applicable.

Property Value

An object that implements the System.Collections.IDictionary interface and contains a collection of user-defined key/value pairs. The default is an empty collection.

Use the System.Collections.IDictionary object returned by the Data property to store and retrieve supplementary information relevant to the exception. The information is in the form of an arbitrary number of user-defined key/value pairs. The key component of each key/value pair is typically an identifying string, whereas the value component of the pair can be any type of object.

Key/Value Pair Security

The key/value pairs stored in the collection returned by the Data property are not secure. If your application calls a nested series of routines, and each routine contains exception handlers, the resulting call stack contains a hierarchy of those exception handlers. If a lower-level routine throws an exception, any upper-level exception handler in the call stack hierarchy can read and/or modify the key/value pairs stored in the collection by any other exception handler. This means you must guarantee that the information in the key/value pairs is not confidential and that your application will operate correctly if the information in the key/value pairs is corrupted.

Key Conflicts

A key conflict occurs when different exception handlers specify the same key to access a key/value pair. Use caution when developing your application because the consequence of a key conflict is that lower-level exception handlers can inadvertently communicate with higher-level exception handlers, and this communication might cause subtle program errors. However, if you are cautious you can use key conflicts to enhance your application.

Avoiding Key Conflicts

Avoid key conflicts by adopting a naming convention to generate unique keys for key/value pairs. For example, a naming convention might yield a key that consists of the period-delimited name of your application, the method that provides supplementary information for the pair, and a unique identifier.

Suppose two applications, named Products and Suppliers, each has a method named Sales. The Sales method in the Products application provides the identification number (the stock keeping unit or SKU) of a product. The Sales method in the Suppliers application provides the identification number, or SID, of a supplier. Consequently, the naming convention for this example yields the keys, "Products.Sales.SKU" and "Suppliers.Sales.SID".

Exploiting Key Conflicts

Exploit key conflicts by using the presence of one or more special, prearranged keys to control processing. Suppose, in one scenario, the highest level exception handler in the call stack hierarchy catches all exceptions thrown by lower-level exception handlers. If a key/value pair with a special key exists, the high-level exception handler formats the remaining key/value pairs in the IDictionary object in some nonstandard way; otherwise, the remaining key/value pairs are formatted in some normal manner.

Now suppose, in another scenario, the exception handler at each level of the call stack hierarchy catches the exception thrown by the next lower-level exception handler. In addition, each exception handler knows the collection returned by the Data property contains a set of key/value pairs that can be accessed with a prearranged set of keys.

Each exception handler uses the prearranged set of keys to update the value component of the corresponding key/value pair with information unique to that exception handler. After the update process is complete, the exception handler throws the exception to the next higher-level exception handler. Finally, the highest level exception handler accesses the key/value pairs and displays the consolidated update information from all the lower-level exception handlers.

NoteNote:

The ExecutionEngineException, OutOfMemoryException, StackOverflowException and ThreadAbortException classes always return a null reference (Nothing in Visual Basic) for the value of the Data property.

The following example demonstrates how to add and retrieve information using the Data property.

// This example demonstrates the Exception.Data property.
using namespace System;
using namespace System::Collections;
void NestedRunTest( bool displayDetails ); // forward declarations

void NestedRoutine1( bool displayDetails );
void NestedRoutine2( bool displayDetails );
void RunTest( bool displayDetails );

int main()
{
   Console::WriteLine();
   Console::WriteLine( "Exception with some extra information..." );
   RunTest( false );
   Console::WriteLine();
   Console::WriteLine( "Exception with all extra information..." );
   RunTest( true );
}

void RunTest( bool displayDetails )
{
   try
   {
      NestedRoutine1( displayDetails );
   }
   catch ( Exception^ e ) 
   {
      Console::WriteLine( "An exception was thrown." );
      Console::WriteLine( e->Message );
      if ( e->Data != nullptr )
      {
         Console::WriteLine( "  Extra details:" );

         for each (DictionaryEntry de in e->Data)
            Console::WriteLine("    The key is '{0}' and the value is: {1}", 
                                                 de.Key, de.Value);
      }
   }
}

void NestedRoutine1( bool displayDetails )
{
   try
   {
      NestedRoutine2( displayDetails );
   }
   catch ( Exception^ e ) 
   {
      e->Data[ "ExtraInfo" ] = "Information from NestedRoutine1.";
      e->Data->Add( "MoreExtraInfo", "More information from NestedRoutine1." );
      throw e;
   }
}

void NestedRoutine2( bool displayDetails )
{
   Exception^ e = gcnew Exception( "This statement is the original exception message." );
   if ( displayDetails )
   {
      String^ s = "Information from NestedRoutine2.";
      int i = -903;
      DateTime dt = DateTime::Now;
      e->Data->Add( "stringInfo", s );
      e->Data[ "IntInfo" ] = i;
      e->Data[ "DateTimeInfo" ] = dt;
   }

   throw e;
}

/*
This example produces the following results:

Exception with some extra information...
An exception was thrown.
This statement is the original exception message.
  Extra details:
    The key is 'ExtraInfo' and the value is: Information from NestedRoutine1.
    The key is 'MoreExtraInfo' and the value is: More information from NestedRoutine1.

Exception with all extra information...
An exception was thrown.
This statement is the original exception message.
  Extra details:
    The key is 'stringInfo' and the value is: Information from NestedRoutine2.
    The key is 'IntInfo' and the value is: -903
    The key is 'DateTimeInfo' and the value is: 11/26/2002 2:12:58 PM
    The key is 'ExtraInfo' and the value is: Information from NestedRoutine1.
    The key is 'MoreExtraInfo' and the value is: More information from NestedRoutine1.
*/

// This example demonstrates the Exception.Data property.
import System.*;
import System.Collections.*;

class Sample
{
    public static void main(String[] args)
    {
        Console.WriteLine();
        Console.WriteLine("Exception with some extra information...");
        RunTest(false);
        Console.WriteLine();
        Console.WriteLine("Exception with all extra information...");
        RunTest(true);
    } //main
    
    public static void RunTest(boolean displayDetails)
    {
        try {
            NestedRoutine1(displayDetails);
        }
        catch (System.Exception e) {
            Console.WriteLine("An exception was thrown.");
            Console.WriteLine(e.get_Message());
            if (e.get_Data() != null) {
                Console.WriteLine("  Extra details:");
                DictionaryEntry de; 
                IEnumerator enumObj = e.get_Data().GetEnumerator();
                while (enumObj.MoveNext()) {
                    de = (DictionaryEntry)enumObj.get_Current();
                    Console.WriteLine("    The key is '{0}' and the value " 
                        + "is: {1}", de.get_Key(), de.get_Value());
                }
            }
        }
    } //RunTest

    public static void NestedRoutine1(boolean displayDetails) 
        throws System.Exception 
    {
        try {
            NestedRoutine2(displayDetails);
        }
        catch (System.Exception e) {
            e.get_Data().set_Item("ExtraInfo",
                "Information from NestedRoutine1.");
            e.get_Data().Add("MoreExtraInfo",
                "More information from NestedRoutine1.");
            throw e;
        }
    } //NestedRoutine1

    public static void NestedRoutine2(boolean displayDetails) 
        throws System.Exception 
    {
        System.Exception e = new Exception("This statement is the original "
            + "exception message.");

        if (displayDetails) {
            String s = "Information from NestedRoutine2.";
            int i = -903;
            DateTime dt = DateTime.get_Now();
            e.get_Data().Add("stringInfo", s);
            e.get_Data().set_Item("IntInfo", (Int32)i);
            e.get_Data().set_Item("DateTimeInfo", dt);
        }
        throw e;
    } //NestedRoutine2
} //Sample
/*
This example produces the following results:

Exception with some extra information...
An exception was thrown.
This statement is the original exception message.
  Extra details:
    The key is 'ExtraInfo' and the value is: Information from NestedRoutine1.
    The key is 'MoreExtraInfo' and the value is: More information from 
    NestedRoutine1.

Exception with all extra information...
An exception was thrown.
This statement is the original exception message.
  Extra details:
    The key is 'stringInfo' and the value is: Information from NestedRoutine2.
    The key is 'IntInfo' and the value is: -903
    The key is 'DateTimeInfo' and the value is: 11/26/2002 2:12:58 PM
    The key is 'ExtraInfo' and the value is: Information from NestedRoutine1.
    The key is 'MoreExtraInfo' and the value is: More information from 
    NestedRoutine1.
*/

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0

Community Additions

Show:
© 2014 Microsoft