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

Mithilfe von Infoattributen erhalten Sie Informationen zum Aufrufer einer Methode. Sie erhalten den Dateipfad des Quellcodes, die Zeilennummer im Quellcode und den Membernamen des Aufrufers. Um Memberaufruferinformationen abzurufen, verwenden Sie Attribute, die auf optionale Parameter angewendet werden. Jeder optionale Parameter gibt einen Standardwert an. In der folgenden Tabelle sind die Caller Info-Attribute aufgeführt, die System.Runtime.CompilerServices im Namespace definiert sind:

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 als optional angegeben sind. Die Aufruferinformationsattribute machen keinen Parameter optional. Stattdessen wirken sie sich auf den Standardwert aus, der übergeben wird, wenn das Argument weggelassen wird. Aufruferinformationenwerte werden zur Kompilierungszeit als Literale in die Zwischensprache (IL) ausgegeben. 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

Sie können das CallerMemberName Attribut verwenden, 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.

Argumentausdrücke

Sie verwenden 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 würden sie aufrufen, 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>

Mit diesem Attribut 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 würde 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

• Benannte und optionale Argumente
• System.Reflection
• Attribute
• Attribute