Determinar informações do chamador usando atributos interpretados pelo compilador C#

Usando atributos info, você obtém informações sobre o chamador para um método. Você obtém o caminho do arquivo do código-fonte, o número da linha no código-fonte e o nome do membro do chamador. Para obter informações do autor da chamada, utilize atributos que são aplicados a parâmetros opcionais. Cada parâmetro opcional especifica um valor padrão. A tabela a seguir lista os atributos Caller Info definidos no System.Runtime.CompilerServices namespace:

Essas informações ajudam você a rastrear e depurar e a criar ferramentas de diagnóstico. 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 inseridas para os argumentos para os parâmetros opcionais.

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

Você especifica um valor padrão explícito para cada parâmetro opcional. Não é possível 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, afetam o valor padrão passado quando o argumento é omitido. Os valores de informações do chamador são emitidos como literais para a linguagem intermediária (IL) em tempo de compilação. Ao contrário dos resultados da StackTrace propriedade para exceções, a ofuscação não afeta os resultados. Você pode fornecer explicitamente os argumentos opcionais para controlar as informações do chamador ou ocultar as 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. Usando essa técnica, você evita o problema de que Renomear refatoração não altera os String valores. Este benefício é especialmente útil para as seguintes tarefas:

• Utilização de rotinas de rastreio e diagnóstico.
• Implementação da INotifyPropertyChanged interface ao vincular dados. Esta interface permite que a propriedade de um objeto notifique um controlo limitado de que a propriedade mudou. O controle pode exibir as informações atualizadas. Sem o CallerMemberName atributo, 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 CallerMemberName atributo.

Expressões de argumento

Use o System.Runtime.CompilerServices.CallerArgumentExpressionAttribute quando quiser que a expressão seja passada como um argumento. As bibliotecas de diagnóstico podem fornecer mais detalhes sobre as expressões passadas aos 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. Essa informação extra facilita a correção.

O exemplo a seguir mostra como você pode fornecer informações detalhadas sobre o argumento quando ele é inválido:

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

Você o invocaria como mostrado no exemplo a seguir:

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

O compilador injeta a expressão usada para condition no message argumento. Quando um desenvolvedor chama Operation com um null argumento, a seguinte mensagem é armazenada no ArgumentException:

Argument failed validation: <func is not null>

Esse atributo permite que você escreva utilitários de diagnóstico que fornecem mais detalhes. Os desenvolvedores podem entender mais rapidamente quais alterações são necessárias. Também pode usar o CallerArgumentExpressionAttribute para determinar que expressão foi usada como recetor para os membros de extensão. O método seguinte recolhe amostras de uma sequência a intervalos regulares. Se a sequência tiver menos elementos do que a frequência, ela relata um erro:

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;
        }
    }
}

O exemplo anterior usa o nameof operador para o parâmetro sequence. Você pode chamar esse método da seguinte maneira:

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

O exemplo anterior lançaria uma ArgumentException mensagem cuja mensagem é o seguinte texto:

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

Ver também

• Argumentos nomeados e opcionais
• System.Reflection
• Attribute
• Atributos