Informações do chamador (Visual Basic)

  • Artigo

Ao usar atributos de informações do chamador, você pode obter informações sobre o chamador de um método. Você pode obter o caminho do arquivo do código-fonte, o número da linha no código-fonte e o nome do membro do chamador. Essas informações são úteis para fins de rastreamento, depuração e criação de ferramentas de diagnóstico.

Para obter essas informações, você deve usar os atributos que são aplicadas aos parâmetros opcionais, cada qual com um valor padrão. A tabela a seguir lista os atributos de informações do chamador que são definidos no namespace de System.Runtime.CompilerServices:

Atributo Descrição Type
CallerFilePathAttribute O caminho completo do arquivo de origem que contém o chamador. Esse é o caminho do arquivo no momento da compilação. String
CallerLineNumberAttribute Número da linha no arquivo fonte no qual o método é chamado. Integer
CallerMemberNameAttribute Nome do método ou da propriedade do chamador. Consulte Nomes dos membros mais adiante neste tópico. String
CallerArgumentExpressionAttribute Expressão usada pelo chamador para um argumento. Consulte Expressões de Chamador adiante, neste tópico. String

Exemplo

O exemplo a seguir mostra como usar os atributos de informações do chamador. Em cada chamada para o método TraceMessage, as informações do chamador são substituídas como argumentos para os parâmetros opcionais.

Private Sub DoProcessing()  
    TraceMessage("Something happened.")  
End Sub  
  
Public Sub TraceMessage(message As String,  
        <System.Runtime.CompilerServices.CallerMemberName> Optional memberName As String = Nothing,  
        <System.Runtime.CompilerServices.CallerFilePath> Optional sourcefilePath As String = Nothing,  
        <System.Runtime.CompilerServices.CallerLineNumber()> Optional sourceLineNumber As Integer = 0)  
  
    System.Diagnostics.Trace.WriteLine("message: " & message)  
    System.Diagnostics.Trace.WriteLine("member name: " & memberName)  
    System.Diagnostics.Trace.WriteLine("source file path: " & sourcefilePath)  
    System.Diagnostics.Trace.WriteLine("source line number: " & sourceLineNumber)  
End Sub  
  
' Sample output:  
'   message: Something happened.  
'   member name: DoProcessing  
'   source file path: C:\Users\username\Documents\Visual Studio 2012\Projects\CallerInfoVB\CallerInfoVB\Form1.vb  
'   source line number: 15

Comentários

Você deve especificar um valor padrão explícito para cada parâmetro opcional. Você não pode aplicar atributos de informações do chamador aos parâmetros que não são especificados como opcionais.

Os atributos de informações do chamador não tornam um parâmetro opcional. Em vez disso, eles afetam o valor padrão que é passado quando o argumento é omitido.

Os valores de informações do chamador são emitidos como literais em linguagem intermediária (IL) em tempo de compilação. Ao contrário dos resultados da propriedade StackTrace para exceções, os resultados não são afetados por ofuscamento.

Você pode fornecer explicitamente os argumentos opcionais para controlar as informações do chamador ou ocultá-las.

Nomes dos membros

Você pode usar o atributo CallerMemberName para evitar especificar o nome do membro como um argumento String ao método chamado. Ao usar essa técnica, você evita o problema de que a Refatoração de Renomeação não altera os valores de String. Esse benefício é especialmente útil para as seguintes tarefas:

  • Usar rotinas de rastreamento e diagnóstico.

  • Implementando a interface INotifyPropertyChanged ao associar dados. Essa interface permite que a propriedade de um objeto notifique um controle associado sobre a alteração da propriedade de modo que o controle possa exibir as informações atualizadas. Sem o atributo CallerMemberName, você deve especificar o nome da propriedade como um literal.

O gráfico a seguir mostra os nomes de membros que são retornados quando você usa o atributo CallerMemberName.

As chamadas ocorrem em Resultado de nome de membro
Método, propriedade ou evento O nome do método, da propriedade ou do evento em que a chamada foi originada.
Construtor A cadeia de caracteres “.ctor”
Construtor estático A cadeia de caracteres “.cctor”
Destruidor A cadeia de caracteres "Finalize"
Operadores usuário ou conversões definidos pelo usuário O nome gerado para o membro, por exemplo, “op_Addition”.
Construtor de atributos O nome do membro ao qual o atributo se aplica. Se o atributo é qualquer elemento dentro de um membro (como um parâmetro, um valor de retorno, ou um parâmetro de tipo genérico), esse resultado é o nome do membro associado a esse elemento.
Nenhum membro contentor (por exemplo, nível de assembly ou atributos que são aplicadas aos tipos) O valor padrão do parâmetro opcional.

Expressões de chamador

Você usa o System.Runtime.CompilerServices.CallerArgumentExpressionAttribute quando quer capturar a expressão usada para um argumento. As bibliotecas de diagnóstico podem querer fornecer mais detalhes sobre as expressões passadas para um argumento. Ao fornecer a expressão que disparou o diagnóstico, além do nome do parâmetro, os desenvolvedores têm mais detalhes sobre a condição que disparou o diagnóstico. Essas informações extras facilitam a correção. O método a seguir usa o CallerArgumentExpressionAttribute para exibir a condição que deve ser True:

Public Shared Sub ValidateArgument(ByVal parameterName As String,
ByVal condition As Boolean,
<CallerArgumentExpression("condition")> ByVal Optional message As String? = Nothing)
    If Not condition Then
        Throw New ArgumentException($"Argument failed validation: <{message}>", parameterName)
    End If
End Sub

Confira também