Compartilhar via

Informações do chamador (Visual Basic)

Usando atributos de Informações do Chamador, você pode obter informações sobre o chamador para 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 rastrear, depurar e criar ferramentas de diagnóstico.

Para obter essas informações, use atributos que são aplicados a parâmetros opcionais, cada um deles com um valor padrão. A tabela a seguir lista os atributos de Informações do Chamador definidos no System.Runtime.CompilerServices namespace:

Atributo Descrição Tipo
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 de linha no arquivo de origem no qual o método é chamado. Integer
CallerMemberNameAttribute Nome do método ou da propriedade do chamador. Consulte os Nomes de Membros mais adiante neste tópico. String
CallerArgumentExpressionAttribute Expressão usada pelo chamador para um argumento. Veja Expressões de Chamador mais adiante neste tópico. String

Exemplo

O exemplo a seguir mostra como usar atributos de Informações do Chamador. Em cada chamada para o TraceMessage método, 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

Observações

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 a 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 passado quando o argumento é omitido.

Os valores de Informações do Chamador são emitidos como literais na IL (Linguagem Intermediária) no momento da compilação. Ao contrário dos resultados da StackTrace propriedade para exceções, os resultados não são afetados pela ofuscação.

Você pode fornecer explicitamente os argumentos opcionais para controlar as informações do chamador ou ocultar informações do chamador.

Nomes dos membros

Você pode usar o CallerMemberName atributo para evitar especificar o nome do membro como um String argumento para o 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 INotifyPropertyChanged interface ao associar dados. Essa interface permite que a propriedade de um objeto notifique um controle associado de que a propriedade foi alterada, para que o controle possa exibir as informações atualizadas. Sem o atributo CallerMemberName, você deve especificar o nome da propriedade como um valor literal.

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

As chamadas ocorrem em Resultado de nome de membro
Método, propriedade ou evento O nome do método, propriedade ou evento do qual a chamada se originou.
Construtor A cadeia de caracteres “.ctor”
Construtor estático A cadeia de caracteres “.cctor”
Destruidor A cadeia de caracteres "Finalize"
Operadores 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 é aplicado. Se o atributo for qualquer elemento dentro de um membro (como um parâmetro, um valor retornado ou um parâmetro de tipo genérico), esse resultado será 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 deseja capturar a expressão usada para um argumento. As bibliotecas de diagnóstico podem querer fornecer mais detalhes sobre as expressões passadas como argumentos. 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 a 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

Consulte também