Freigeben über

Ermitteln von Aufruferinformationen mithilfe von Attributen, die der C#-Compiler interpretiert

Mithilfe von Infoattributen können Sie Informationen zum Aufrufer einer Methode abrufen. Sie können den Dateipfad des Quellcodes, die Zeilennummer im Quellcode und den Membernamen des Aufrufers abrufen. Verwenden Sie Attribute, die Sie auf optionale Parameter anwenden, um Memberaufruferinformationen abzurufen. Jeder optionale Parameter gibt einen Standardwert an.

Die C#-Sprachreferenz dokumentiert die zuletzt veröffentlichte Version der C#-Sprache. Außerdem enthält sie erste Dokumentation für Features in der öffentlichen Vorschau für die kommende Sprachversion.

In der Dokumentation werden alle Features identifiziert, die in den letzten drei Versionen der Sprache oder in der aktuellen öffentlichen Vorschau eingeführt wurden.

Tipp

Informationen dazu, wann ein Feature erstmals in C# eingeführt wurde, finden Sie im Artikel zum Versionsverlauf der C#-Sprache.

In der folgenden Tabelle sind die Caller Info-Attribute aufgeführt, die System.Runtime.CompilerServices im Namespace definiert sind:

Merkmal Description Typ
CallerFilePathAttribute Vollständiger Pfad der Quelldatei, die den Aufrufer enthält. Der vollständige Pfad ist der Pfad zur Kompilierungszeit. String
CallerLineNumberAttribute Zeilennummer in der Quelldatei, aus der die Methode aufgerufen wird. Integer
CallerMemberNameAttribute Methodenname oder Eigenschaftsname des Aufrufers. String
CallerArgumentExpressionAttribute Zeichenfolgendarstellung des Argumentausdrucks. String

Diese Informationen helfen Ihnen bei der Ablaufverfolgung und beim Debuggen und beim Erstellen von Diagnosetools. Das folgende Beispiel zeigt, wie Aufruferinformationenattribute verwendet werden. Bei jedem Aufruf der TraceMessage Methode werden die Aufruferinformationen für die Argumente an die optionalen Parameter eingefügt.

public void DoProcessing()
{
    TraceMessage("Something happened.");
}

public void TraceMessage(string message,
        [CallerMemberName] string memberName = "",
        [CallerFilePath] string sourceFilePath = "",
        [CallerLineNumber] int sourceLineNumber = 0)
{
    Trace.WriteLine("message: " + message);
    Trace.WriteLine("member name: " + memberName);
    Trace.WriteLine("source file path: " + sourceFilePath);
    Trace.WriteLine("source line number: " + sourceLineNumber);
}

// Sample Output:
//  message: Something happened.
//  member name: DoProcessing
//  source file path: c:\Visual Studio Projects\CallerInfoCS\CallerInfoCS\Form1.cs
//  source line number: 31

Sie geben einen expliziten Standardwert für jeden optionalen Parameter an. Sie können Aufruferinformationenattribute nicht auf Parameter anwenden, die nicht optional sind. Die Aufruferinformationsattribute machen keinen Parameter optional. Stattdessen wirken sie sich auf den Standardwert aus, der übergeben wird, wenn das Argument weggelassen wird. Der Compiler emittiert Aufruferinfowerte als Literale zur Kompilierungszeit in die Zwischensprache (IL). Im Gegensatz zu den Ergebnissen der StackTrace Eigenschaft für Ausnahmen wirkt sich die Verschleierung nicht auf die Ergebnisse aus. Sie können explizit die optionalen Argumente angeben, um die Aufruferinformationen zu steuern oder Aufruferinformationen auszublenden.

Membernamen

Verwenden Sie das CallerMemberName Attribut, um die Angabe des Membernamens als String Argument für die aufgerufene Methode zu vermeiden. Mithilfe dieser Technik vermeiden Sie das Problem, dass die Umgestaltung umbenennen die String Werte nicht ändert. Dieser Vorteil ist besonders nützlich für die folgenden Aufgaben:

  • Verwenden von Ablaufverfolgungs- und Diagnoseroutinen.
  • Implementieren der INotifyPropertyChanged Schnittstelle beim Binden von Daten. Diese Schnittstelle ermöglicht es der Eigenschaft eines Objekts, ein gebundenes Steuerelement zu benachrichtigen, dass die Eigenschaft geändert wurde. Das Steuerelement kann die aktualisierten Informationen anzeigen. Ohne das CallerMemberName Attribut müssen Sie den Eigenschaftsnamen als Literal angeben.

Das folgende Diagramm zeigt die Membernamen, die zurückgegeben werden, wenn Sie das CallerMemberName Attribut verwenden.

Anrufe innerhalb von Ergebnis des Membernamens
Methode, Eigenschaft oder Ereignis Der Name der Methode, Eigenschaft oder des Ereignisses, von dem der Aufruf stammt.
Konstruktor Die Zeichenfolge ".ctor"
Statischer Konstruktor Die Zeichenfolge ".cctor"
Finalizer Die Zeichenfolge "Finalize"
Benutzerdefinierte Operatoren oder Konvertierungen Der generierte Name für das Element, z. B. "op_Addition".
Attributkonstruktor Der Name der Methode oder Eigenschaft, auf die das Attribut angewendet wird. Wenn es sich bei dem Attribut um ein Element innerhalb eines Elements handelt (z. B. einen Parameter, einen Rückgabewert oder einen generischen Typparameter), ist dieses Ergebnis der Name des elements, das diesem Element zugeordnet ist.
Kein enthaltenes Element (z. B. Assemblyebene oder Attribute, die auf Typen angewendet werden) Der Standardwert des optionalen Parameters.

Argumentausdrücke

Verwenden Sie den System.Runtime.CompilerServices.CallerArgumentExpressionAttribute Zeitpunkt, an dem der Ausdruck als Argument übergeben werden soll. Diagnosebibliotheken können weitere Details zu den an Argumente übergebenen Ausdrücken bereitstellen. Durch Bereitstellen des Ausdrucks, der die Diagnose ausgelöst hat, verfügen Entwickler zusätzlich zum Parameternamen über weitere Details zu der Bedingung, die die Diagnose ausgelöst hat. Diese zusätzlichen Informationen erleichtern das Beheben.

Das folgende Beispiel zeigt, wie Sie detaillierte Informationen zum Argument bereitstellen können, wenn es ungültig ist:

public static void ValidateArgument(string parameterName, bool condition, [CallerArgumentExpression("condition")] string? message=null)
{
    if (!condition)
    {
        throw new ArgumentException($"Argument failed validation: <{message}>", parameterName);
    }
}

Sie rufen sie auf, wie im folgenden Beispiel gezeigt:

public void Operation(Action func)
{
    Utilities.ValidateArgument(nameof(func), func is not null);
    func();
}

Der Compiler fügt den ausdruck ein, der in das condition Argument verwendet wirdmessage. Wenn ein Entwickler mit einem Argument aufruftOperation, wird die folgende Meldung in der nullDatei gespeichert:ArgumentException

Argument failed validation: <func is not null>

Mithilfe dieses Attributs können Sie Diagnosehilfsprogramme schreiben, die weitere Details bereitstellen. Entwickler können schneller verstehen, welche Änderungen erforderlich sind. Sie können auch den CallerArgumentExpressionAttribute Ausdruck bestimmen, der als Empfänger für Erweiterungselemente verwendet wurde. Die folgende Methode gibt eine Sequenz in regelmäßigen Abständen an. Wenn die Sequenz weniger Elemente aufweist als die Häufigkeit, meldet sie einen Fehler:

extension<T>(IEnumerable<T> sequence)
{
    public IEnumerable<T> Sample(int frequency, 
        [CallerArgumentExpression(nameof(sequence))] string? message = null)
    {
        if (sequence.Count() < frequency)
            throw new InvalidOperationException($"Expression doesn't have enough elements: {message}");
        int i = 0;
        foreach (T item in sequence)
        {
            if (i++ % frequency == 0)
                yield return item;
        }
    }
}

Im vorherigen Beispiel wird der nameof Operator für den Parameter sequenceverwendet. Sie können diese Methode wie folgt aufrufen:

sample = Enumerable.Range(0, 10).Sample(100);

Im vorherigen Beispiel wird eine ArgumentException Nachricht ausgelöst, deren Nachricht der folgende Text ist:

Expression doesn't have enough elements: Enumerable.Range(0, 10) (Parameter 'sequence')

Siehe auch

  • Last updated on