Exception.Data Propriété

Définition

Obtient une collection de paires clé/valeur qui fournissent des informations supplémentaires définies par l’utilisateur sur l’exception.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

Valeur de propriété

Objet qui implémente l'interface IDictionary et contient une collection de paires clé/valeur définies par l'utilisateur.An object that implements the IDictionary interface and contains a collection of user-defined key/value pairs. La valeur par défaut est une collection vide.The default is an empty collection.

Exemples

L’exemple suivant montre comment ajouter et récupérer des informations à l' Data aide de la propriété.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. 

Remarques

Utilisez l' System.Collections.IDictionary objet retourné par la Data propriété pour stocker et récupérer des informations supplémentaires relatives à l’exception.Use the System.Collections.IDictionary object returned by the Data property to store and retrieve supplementary information relevant to the exception. Les informations se présente sous la forme d’un nombre arbitraire de paires clé/valeur définies par l’utilisateur.The information is in the form of an arbitrary number of user-defined key/value pairs. Le composant clé de chaque paire clé/valeur est généralement une chaîne d’identification, tandis que le composant valeur de la paire peut être n’importe quel type d’objet.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.

Sécurité des paires clé/valeurKey/Value Pair Security

Les paires clé/valeur stockées dans la collection retournée par Data la propriété ne sont pas sécurisées.The key/value pairs stored in the collection returned by the Data property are not secure. Si votre application appelle une série imbriquée de routines et que chaque routine contient des gestionnaires d’exceptions, la pile des appels résultante contient une hiérarchie de ces gestionnaires d’exceptions.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. Si une routine de niveau inférieur lève une exception, tout gestionnaire d’exceptions de niveau supérieur dans la hiérarchie de la pile des appels peut lire et/ou modifier les paires clé/valeur stockées dans la collection par tout autre gestionnaire d’exceptions.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. Cela signifie que vous devez vous assurer que les informations contenues dans les paires clé/valeur ne sont pas confidentielles et que votre application fonctionne correctement si les informations contenues dans les paires clé/valeur sont endommagées.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.

Conflits de cléKey Conflicts

Un conflit de clé se produit lorsque différents gestionnaires d’exceptions spécifient la même clé pour accéder à une paire clé/valeur.A key conflict occurs when different exception handlers specify the same key to access a key/value pair. Soyez prudent lors du développement de votre application, car la conséquence d’un conflit de clés est que les gestionnaires d’exceptions de niveau inférieur peuvent communiquer par inadvertance avec les gestionnaires d’exceptions de niveau supérieur, et cette communication peut entraîner des erreurs de programme subtiles.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. Toutefois, si vous êtes prudent, vous pouvez utiliser des conflits de clé pour améliorer votre application.However, if you are cautious you can use key conflicts to enhance your application.

Éviter les conflits de cléAvoiding Key Conflicts

Évitez les conflits de clé en adoptant une convention d’affectation de noms pour générer des clés uniques pour les paires clé/valeur.Avoid key conflicts by adopting a naming convention to generate unique keys for key/value pairs. Par exemple, une convention d’affectation de noms peut générer une clé qui se compose du nom délimité par des points de votre application, de la méthode qui fournit des informations supplémentaires pour la paire et d’un identificateur unique.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.

Supposons que deux applications, nommées Products et Suppliers, disposent chacune d’une méthode nommée Sales.Suppose two applications, named Products and Suppliers, each has a method named Sales. La méthode Sales de l’application Products fournit le numéro d’identification (l’unité de conservation de stock ou la référence SKU) d’un produit.The Sales method in the Products application provides the identification number (the stock keeping unit or SKU) of a product. La méthode Sales de l’application Suppliers fournit le numéro d’identification, ou SID, d’un fournisseur.The Sales method in the Suppliers application provides the identification number, or SID, of a supplier. Par conséquent, la Convention d’affectation de noms pour cet exemple produit les clés « Products. sales. SKU » et « Suppliers. sales. SID ».Consequently, the naming convention for this example yields the keys, "Products.Sales.SKU" and "Suppliers.Sales.SID".

Exploitation des conflits de cléExploiting Key Conflicts

Exploitez les conflits de clé en utilisant la présence d’une ou de plusieurs clés spéciales préorganisées pour contrôler le traitement.Exploit key conflicts by using the presence of one or more special, prearranged keys to control processing. Supposons que, dans un scénario, le gestionnaire d’exceptions de niveau le plus élevé dans la hiérarchie des piles d’appels intercepte toutes les exceptions levées par les gestionnaires d’exceptions de niveau inférieur.Suppose, in one scenario, the highest level exception handler in the call stack hierarchy catches all exceptions thrown by lower-level exception handlers. Si une paire clé/valeur avec une clé spéciale existe, le gestionnaire d’exceptions de haut niveau met en forme les paires clé/valeur IDictionary restantes dans l’objet de façon non standard ; sinon, les paires clé/valeur restantes sont mises en forme de façon normale.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.

Supposons maintenant que, dans un autre scénario, le gestionnaire d’exceptions à chaque niveau de la hiérarchie de la pile des appels intercepte l’exception levée par le gestionnaire d’exceptions de niveau inférieur suivant.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. En outre, chaque gestionnaire d’exceptions sait que la collection retournée par la Data propriété contient un ensemble de paires clé/valeur accessibles à l’aide d’un jeu de clés préarrangé.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.

Chaque gestionnaire d’exceptions utilise l’ensemble de clés prédéfinies pour mettre à jour le composant de valeur de la paire clé/valeur correspondante avec les informations uniques à ce gestionnaire d’exceptions.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. Une fois le processus de mise à jour terminé, le gestionnaire d’exceptions lève l’exception vers le gestionnaire d’exceptions de niveau supérieur suivant.After the update process is complete, the exception handler throws the exception to the next higher-level exception handler. Enfin, le gestionnaire d’exceptions de niveau le plus élevé accède aux paires clé/valeur et affiche les informations de mise à jour consolidée de tous les gestionnaires d’exceptions de niveau inférieur.Finally, the highest level exception handler accesses the key/value pairs and displays the consolidated update information from all the lower-level exception handlers.

S’applique à

Voir aussi