Exception.Data Propriedade

Definição

Obtém uma coleção de pares de chave/valor que fornecem informações adicionais definidas pelo usuário sobre a exceção.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

Valor da propriedade

Um objeto que implementa a interface IDictionary e que contém uma coleção de pares chave-valor definidos pelo usuário.An object that implements the IDictionary interface and contains a collection of user-defined key/value pairs. O padrão é uma coleção vazia.The default is an empty collection.

Exemplos

O exemplo a seguir demonstra como adicionar e recuperar informações usando a Data propriedade.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. 

Comentários

Use o System.Collections.IDictionary objeto retornado Data pela propriedade para armazenar e recuperar informações suplementares relevantes para a exceção.Use the System.Collections.IDictionary object returned by the Data property to store and retrieve supplementary information relevant to the exception. As informações estão na forma de um número arbitrário de pares de chave/valor definidos pelo usuário.The information is in the form of an arbitrary number of user-defined key/value pairs. O principal componente de cada par chave/valor normalmente é uma cadeia de caracteres de identificação, enquanto que o componente de valor do par pode ser qualquer tipo de objeto.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.

Segurança do par de chave/valorKey/Value Pair Security

Os pares de chave/valor armazenados na coleção retornada pela Data propriedade não são seguros.The key/value pairs stored in the collection returned by the Data property are not secure. Se seu aplicativo chamar uma série aninhada de rotinas e cada rotina contiver manipuladores de exceção, a pilha de chamadas resultante conterá uma hierarquia desses manipuladores de exceção.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. Se uma rotina de nível inferior lançar uma exceção, qualquer manipulador de exceção de nível superior na hierarquia da pilha de chamadas poderá ler e/ou modificar os pares de chave/valor armazenados na coleção por qualquer outro manipulador de exceção.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. Isso significa que você deve garantir que as informações nos pares chave/valor não sejam confidenciais e que seu aplicativo funcionará corretamente se as informações nos pares chave/valor estiverem corrompidas.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.

Conflitos de chaveKey Conflicts

Um conflito de chave ocorre quando diferentes manipuladores de exceção especificam a mesma chave para acessar um par de chave/valor.A key conflict occurs when different exception handlers specify the same key to access a key/value pair. Tenha cuidado ao desenvolver seu aplicativo porque a consequência de um conflito de chave é que os manipuladores de exceção de nível inferior podem se comunicar inadvertidamente com manipuladores de exceção de nível mais alto, e essa comunicação pode causar erros sutis do programa.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. No entanto, se você tiver cuidado, poderá usar conflitos de chave para aprimorar seu aplicativo.However, if you are cautious you can use key conflicts to enhance your application.

Evitando conflitos de chaveAvoiding Key Conflicts

Evite conflitos de chave adotando uma Convenção de nomenclatura para gerar chaves exclusivas para pares de chave/valor.Avoid key conflicts by adopting a naming convention to generate unique keys for key/value pairs. Por exemplo, uma Convenção de nomenclatura pode produzir uma chave que consiste no nome delimitado por período de seu aplicativo, o método que fornece informações suplementares para o par e um identificador exclusivo.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.

Suponha que dois aplicativos, chamados produtos e fornecedores, cada um tenha um método chamado Sales.Suppose two applications, named Products and Suppliers, each has a method named Sales. O método Sales no aplicativo Products fornece o número de identificação (a unidade de manutenção de estoque ou SKU) de um produto.The Sales method in the Products application provides the identification number (the stock keeping unit or SKU) of a product. O método Sales no aplicativo suppliers fornece o número de identificação, ou SID, de um fornecedor.The Sales method in the Suppliers application provides the identification number, or SID, of a supplier. Consequentemente, a Convenção de nomenclatura para este exemplo gera as chaves "Products. Sales. SKU" e "Suppliers. Sales. SID".Consequently, the naming convention for this example yields the keys, "Products.Sales.SKU" and "Suppliers.Sales.SID".

Explorando conflitos de chaveExploiting Key Conflicts

Explorar conflitos de chave usando a presença de uma ou mais chaves preorganizadas especiais para controlar o processamento.Exploit key conflicts by using the presence of one or more special, prearranged keys to control processing. Suponha que, em um cenário, o manipulador de exceção de nível mais alto na hierarquia de pilha de chamadas captura todas as exceções geradas por manipuladores de exceção de nível inferior.Suppose, in one scenario, the highest level exception handler in the call stack hierarchy catches all exceptions thrown by lower-level exception handlers. Se um par de chave/valor com uma chave especial existir, o manipulador de exceção de alto nível formatará os pares de chave/ IDictionary valor restantes no objeto de alguma forma não padrão; caso contrário, os pares de chave/valor restantes serão formatados de forma normal.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.

Agora suponha que, em outro cenário, o manipulador de exceção em cada nível da hierarquia da pilha de chamadas captura a exceção lançada pelo próximo manipulador de exceção de nível inferior.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. Além disso, cada manipulador de exceção sabe que a coleção retornada Data pela propriedade contém um conjunto de pares de chave/valor que pode ser acessado com um conjunto de chaves predefinido.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.

Cada manipulador de exceção usa o conjunto predefinido de chaves para atualizar o componente de valor do par chave/valor correspondente com informações exclusivas para esse manipulador de exceção.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. Após a conclusão do processo de atualização, o manipulador de exceção gera a exceção para o próximo manipulador de exceção de nível superior.After the update process is complete, the exception handler throws the exception to the next higher-level exception handler. Por fim, o manipulador de exceção de nível mais alto acessa os pares de chave/valor e exibe as informações de atualização consolidada de todos os manipuladores de exceção de nível inferior.Finally, the highest level exception handler accesses the key/value pairs and displays the consolidated update information from all the lower-level exception handlers.

Aplica-se a

Veja também