Exception.Data Propriedade
Definição
Importante
Algumas informações dizem respeito a um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.
Obtém uma coleção de pares chave/valor que fornecem informação adicional definida pelo utilizador sobre a exceção.
public:
virtual property System::Collections::IDictionary ^ Data { System::Collections::IDictionary ^ get(); };public virtual System.Collections.IDictionary Data { get; }member this.Data : System.Collections.IDictionaryPublic Overridable ReadOnly Property Data As IDictionaryValor de Propriedade
Um objeto que implementa a IDictionary interface e contém uma coleção de pares chave/valor definidos pelo utilizador. O padrão é uma coleção vazia.
Exemplos
O exemplo seguinte demonstra como adicionar e recuperar informação usando a Data propriedade.
// 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.
// This example demonstrates the Exception.Data property.
open System
open System.Collections
let nestedRoutine2 displayDetails =
let e = Exception "This statement is the original exception message."
if displayDetails then
let s = "Information from nestedRoutine2."
let i = -903
let dt = DateTime.Now
e.Data.Add("stringInfo", s)
e.Data["IntInfo"] <- i
e.Data["DateTimeInfo"] <- dt
raise e
let nestedRoutine1 displayDetails =
try
nestedRoutine2 displayDetails
with e ->
e.Data["ExtraInfo"] <- "Information from nestedRoutine1."
e.Data.Add("MoreExtraInfo", "More information from nestedRoutine1.")
reraise ()
let runTest displayDetails =
try
nestedRoutine1 displayDetails
with e ->
printfn "An exception was thrown."
printfn $"{e.Message}"
if e.Data.Count > 0 then
printfn " Extra details:"
for de in e.Data do
let de = de :?> DictionaryEntry
printfn $""" Key: {"'" + de.Key.ToString() + "'",-20} Value: {de.Value}"""
printfn "\nException with some extra information..."
runTest false
printfn "\nException with all extra information..."
runTest true
// 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.
Observações
Use o System.Collections.IDictionary objeto retornado pela Data propriedade para armazenar e recuperar informações suplementares relevantes para a exceção. As informações estão na forma de um número arbitrário de pares chave/valor definidos pelo usuário. O componente chave de cada par chave/valor é normalmente uma cadeia de caracteres de identificação, enquanto o componente de valor do par pode ser qualquer tipo de objeto.
Segurança do par chave/valor
Os pares chave/valor armazenados na coleção retornada pela propriedade Data não são seguros. Se seu aplicativo chama uma série aninhada de rotinas e cada rotina contém manipuladores de exceção, a pilha de chamadas resultante contém uma hierarquia desses manipuladores de exceção. Se uma rotina de nível inferior lançar uma exceção, qualquer manipulador de exceção de nível superior na hierarquia de pilha de chamadas poderá ler e/ou modificar os pares chave/valor armazenados na coleção por qualquer outro manipulador de exceções. Isso significa que você deve garantir que as informações nos pares chave/valor não são confidenciais e que seu aplicativo funcionará corretamente se as informações nos pares chave/valor estiverem corrompidas.
Principais conflitos
Um conflito de chave ocorre quando diferentes manipuladores de exceção especificam a mesma chave para acessar um par chave/valor. Tenha cuidado ao desenvolver seu aplicativo porque a consequência de um conflito de chave é que manipuladores de exceção de nível inferior podem se comunicar inadvertidamente com manipuladores de exceção de nível superior, e essa comunicação pode causar erros sutis de programa. No entanto, se você for cauteloso, você pode usar conflitos de chave para melhorar seu aplicativo.
Evite conflitos importantes
Evite conflitos de chaves adotando uma convenção de nomenclatura para gerar chaves exclusivas para pares chave/valor. Por exemplo, uma convenção de nomenclatura pode gerar uma chave que consiste no nome delimitado por período do seu aplicativo, no método que fornece informações suplementares para o par e em um identificador exclusivo.
Suponha que dois aplicativos, chamados Produtos e Fornecedores, cada um tenha um método chamado Vendas. O método Sales na aplicação Produtos fornece o número identificador (a unidade de manutenção de stock ou SKU) de um produto. O método Sales no aplicativo Fornecedores fornece o número de identificação, ou SID, de um fornecedor. Consequentemente, a convenção de nomenclatura para este exemplo produz as chaves, "Products.Sales.SKU" e "Suppliers.Sales.SID".
Tirar partido de conflitos-chave
Aproveitar conflitos-chave usando a presença de uma ou mais chaves especiais e pré-definidas para controlar o processamento. Suponhamos que, em um cenário, o manipulador de exceções de nível mais alto na hierarquia da pilha de chamadas captura todas as exceções lançadas por manipuladores de exceção de nível inferior. Se existir um par chave/valor com uma chave especial, o manipulador de exceções de alto nível formata os pares chave/valor restantes no objeto de IDictionary alguma forma não padrão, caso contrário, os pares chave/valor restantes são formatados de alguma maneira normal.
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. Além disso, cada manipulador de exceção sabe que a Data coleção retornada pela propriedade contém um conjunto de pares chave/valor que podem ser acessados com um conjunto pré-organizado de chaves.
Cada manipulador de exceção usa o conjunto prearranjado de chaves para atualizar o componente de valor do par chave/valor correspondente com informações exclusivas para esse manipulador de exceções. Após a conclusão do processo de atualização, o manipulador de exceções lança a exceção para o próximo manipulador de exceção de nível superior. Finalmente, o manipulador de exceção de nível mais alto acessa os pares chave/valor e exibe as informações de atualização consolidadas de todos os manipuladores de exceção de nível inferior.
