Exception.Data Exception.Data Exception.Data Exception.Data Property

定義

取得提供例外狀況之其他使用者定義相關資訊的索引鍵/值組集合。Gets a collection of key/value pairs that provide additional user-defined information about the exception.

public:
 virtual property System::Collections::IDictionary ^ Data { System::Collections::IDictionary ^ get(); };
public virtual System.Collections.IDictionary Data { get; }
member this.Data : System.Collections.IDictionary
Public Overridable ReadOnly Property Data As IDictionary

屬性值

實作 IDictionary 介面的物件,含有由使用者定義之索引鍵/值組所組成的集合。An object that implements the IDictionary interface and contains a collection of user-defined key/value pairs. 預設為空集合。The default is an empty collection.

範例

下列範例示範如何使用Data屬性來新增和取出資訊。The following example demonstrates how to add and retrieve information using the 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("\nException with some extra information..." );
   RunTest(false);
   Console::WriteLine("\nException 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("    Key: {0,-20}      Value: {1}", 
                               "'" + de.Key->ToString() + "'", 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;
   }
}

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.
using System;
using System.Collections;

class Sample 
{
   public static void Main()
   {
      Console.WriteLine("\nException with some extra information...");
      RunTest(false);
      Console.WriteLine("\nException with all extra information...");
      RunTest(true);
   }

   public static void RunTest(bool displayDetails)
   {
      try {
         NestedRoutine1(displayDetails);
      }
      catch (Exception e) {
         Console.WriteLine("An exception was thrown.");
         Console.WriteLine(e.Message);
         if (e.Data.Count > 0) {
            Console.WriteLine("  Extra details:");
            foreach (DictionaryEntry de in e.Data)
               Console.WriteLine("    Key: {0,-20}      Value: {1}", 
                                 "'" + de.Key.ToString() + "'", de.Value);
         }
      }
   }
    
   public static 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;
      }
   }
    
   public static void NestedRoutine2(bool displayDetails)
   {
      Exception e = new 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;
   }
}
// The example displays the following output: 
//    Exception with some extra information...
//    An exception was thrown.
//    This statement is the original exception message.
//      Extra details:                                               
//        Key: 'ExtraInfo'               Value: Information from NestedRoutine1.
//        Key: 'MoreExtraInfo'           Value: More information from NestedRoutine1.
//    
//    Exception with all extra information...
//    An exception was thrown.
//    This statement is the original exception message.
//      Extra details:
//        Key: 'stringInfo'              Value: Information from NestedRoutine2.
//        Key: 'IntInfo'                 Value: -903
//        Key: 'DateTimeInfo'            Value: 7/29/2013 10:50:13 AM
//        Key: 'ExtraInfo'               Value: Information from NestedRoutine1.
//        Key: 'MoreExtraInfo'           Value: More information from NestedRoutine1. 
Imports System.Collections

Module Example
   Public Sub Main()
      Console.WriteLine()
      Console.WriteLine("Exception with some extra information...")
      RunTest(False)
      Console.WriteLine()
      Console.WriteLine("Exception with all extra information...")
      RunTest(True)
   End Sub

   Public Sub RunTest(displayDetails As Boolean)
      Try
         NestedRoutine1(displayDetails)
      Catch e As Exception
         Console.WriteLine("An exception was thrown.")
         Console.WriteLine(e.Message)
         If e.Data.Count > 0 Then
            Console.WriteLine("  Extra details:")
            For Each de As DictionaryEntry In e.Data
               Console.WriteLine("    Key: {0,-20}      Value: {1}",
                                 "'" + de.Key.ToString() + "'", de.Value)
            Next
         End If 
      End Try 
   End Sub 

   Public Sub NestedRoutine1(displayDetails As Boolean)
      Try
         NestedRoutine2(displayDetails)
      Catch e As Exception
         e.Data("ExtraInfo") = "Information from NestedRoutine1."
         e.Data.Add("MoreExtraInfo", "More information from NestedRoutine1.")
         Throw e
      End Try 
   End Sub

   Public Sub NestedRoutine2(displayDetails As Boolean)
      Dim e As New Exception("This statement is the original exception message.")
      If displayDetails Then 
         Dim s As String = "Information from NestedRoutine2." 
         Dim i As Integer = -903
         Dim dt As DateTime = DateTime.Now
         e.Data.Add("stringInfo", s)
         e.Data("IntInfo") = i
         e.Data("DateTimeInfo") = dt
      End If 
      Throw e
   End Sub 
End Module
' This example displays the following output: 
'    Exception with some extra information...
'    An exception was thrown.
'    This statement is the original exception message.
'      Extra details:
'        Key: 'ExtraInfo'               Value: Information from NestedRoutine1.
'        Key: 'MoreExtraInfo'           Value: More information from NestedRoutine1.
'    
'    Exception with all extra information...
'    An exception was thrown.
'    This statement is the original exception message.
'      Extra details:
'        Key: 'stringInfo'              Value: Information from NestedRoutine2.
'        Key: 'IntInfo'                 Value: -903
'        Key: 'DateTimeInfo'            Value: 7/29/2013 10:50:13 AM
'        Key: 'ExtraInfo'               Value: Information from NestedRoutine1.
'        Key: 'MoreExtraInfo'           Value: More information from NestedRoutine1. 

備註

使用Data屬性System.Collections.IDictionary所傳回的物件,來儲存和抓取與例外狀況相關的補充資訊。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

儲存在Data屬性所傳回之集合中的索引鍵/值組並不安全。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.

假設有兩個名為 Products 和供應商的應用程式都有一個名為 Sales 的方法。Suppose two applications, named Products and Suppliers, each has a method named Sales. Products 應用程式中的 Sales 方法會提供產品的識別碼(庫存單位或 SKU)。The Sales method in the Products application provides the identification number (the stock keeping unit or SKU) of a product. 供應商應用程式中的 Sales 方法會提供供應商的識別碼(或 SID)。The Sales method in the Suppliers application provides the identification number, or SID, of a supplier. 因此,此範例的命名慣例會產生金鑰 "Products. Sales. SKU" 和 "供應商. Sales. SID"。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. 如果具有特殊索引鍵的索引鍵/值組存在,高階的例外狀況處理常式會以某種非標準的方式來IDictionary格式化物件中剩餘的索引鍵/值組; 否則,其餘的索引鍵/值組會以某種標準方式進行格式化。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. 此外,每個例外狀況處理常式都會知道Data屬性所傳回的集合,其中包含一組索引鍵/值配對,可以使用一組按照預先安排的索引鍵來存取。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.

適用於

另請參閱