Caller Information (Visual Basic) (Сведения о вызывающем (Visual Basic))

  • Статья

С помощью информационных атрибутов вызывающего объекта можно получить сведения о вызывающем объекте метода. Можно получить путь к файлу исходного кода, номер строки в исходном коде и имя вызывающего объекта. Эти сведения полезны для трассировки, отладки и создания средств диагностики.

Для получения этих сведений используются атрибуты, которые применяются к необязательным параметрам, каждый из которых имеет значение по умолчанию. В следующей таблице перечислены информационные атрибуты вызывающего объекта, которые определены в пространстве имен System.Runtime.CompilerServices:

Атрибут Описание Тип
CallerFilePathAttribute Полный путь исходного файла, содержащего вызывающий объект. Это путь к файлу во время компиляции. String
CallerLineNumberAttribute Номер строки в исходном файле, в которой вызывается метод. Integer
CallerMemberNameAttribute Имя свойства или метода вызывающего объекта. См. подраздел Имена членов ниже. String
CallerArgumentExpressionAttribute Выражение, используемое вызывающим для аргумента. См . статью "Выражения вызывающего абонента" далее в этом разделе. String

Пример

В следующем примере показано, как использовать информационные атрибуты вызывающего объекта. При каждом вызове метода TraceMessage сведения о вызывающем объекте подставляются в качестве аргументов необязательных параметров.

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

Замечания

Для каждого необязательного параметра необходимо указать явное значение по умолчанию. Нельзя применять информационные атрибуты вызывающего объекта к параметрам, которые не были указаны как необязательные.

Информационные атрибуты вызывающего объекта не делают параметр необязательным. Вместо этого они влияют на значение по умолчанию, которое передается, если аргумент был опущен.

Информационные значения вызывающего объекта передаются как литералы в IL во время компиляции. В отличие от результатов свойства StackTrace для исключений, результаты не затрагиваются запутыванием кода.

Можно явно передать необязательные аргументы, чтобы управлять сведениями о вызывающем объекте или скрывать сведения о вызывающем объекте.

Имена членов

Можно использовать атрибут CallerMemberName, чтобы не указывать имя члена в виде аргумента String вызываемому методу. Этот прием позволяет избежать проблемы, заключающейся в том, что операция рефакторинга и переименования не изменяет значений String. Это особенно полезно при выполнении следующих задач:

  • Использование процедур трассировки и диагностики.

  • Реализация интерфейса INotifyPropertyChanged при привязке данных. Этот интерфейс позволяет свойству объекта уведомлять связанный элемент управления об изменении свойства, чтобы элемент управления мог отображать обновленные сведения. Если атрибут CallerMemberName не используется, необходимо указать имя свойства как литерал.

В следующей таблице представлены имена членов, возвращаемых при использовании атрибута CallerMemberName.

Фрагмент кода, в пределах которого происходит вызов Результат имени члена
Метод, свойство или событие Имя метода, свойства или события, из которого происходил вызов.
Конструктор Строка ".ctor"
Статический конструктор Строка ".cctor"
Деструктор Строка "Finalize"
Определяемые пользователем операторы и преобразования Созданное имя члена, например, "op_Addition".
Конструктора атрибута Имя члена, к которому применяется атрибут. Если атрибут — любой элемент внутри члена (например, параметр, возвращаемое значение или параметр универсального типа), то результат — имя члена, который связан с этим элементом.
Нет содержащего члена (например, уровень сборки или атрибуты, примененные к типам) Значение необязательного параметра по умолчанию.

Выражения вызывающего абонента

Вы используете, System.Runtime.CompilerServices.CallerArgumentExpressionAttribute когда вы хотите записать выражение, используемое для аргумента. Библиотекам диагностики может потребоваться предоставить дополнительные сведения о выражениях, переданных в качестве аргументов. Предоставляя выражение, запускающее диагностику, помимо имени параметра разработчики получают дополнительные сведения об условии, вызвавшем диагностику. Эти дополнительные сведения упрощают устранение проблемы. В следующем методе CallerArgumentExpressionAttribute используется для отображения условия, которое должно быть 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

См. также