C# 10 新特性 —— CallerArgumentExpression

C# 10 新特性 —— CallerArgumentExpression

Intro

C# 10 支持使用 CallerArgumentExpression 来自动地获取调用方的信息，这可以简化我们现在的一些代码，让代码更加简洁，一起看下面的示例吧

Caller Info

C# 在 5.0 的时候开始支持 Caller Info 自动获取调用方的一些信息，C# 5 开始支持的 Caller Info Attribute 有三个,

• [CallerMemberName] - 调用方成员名称，方法名或者属性名.

• [CallerFilePath] - 调用方源代码所在文件路径

• [CallerLineNumber] - 调用方所在源代码的行数信息

在方法参数中添加一个 Attribute 来获取调用方信息，使用示例如下：

public static void MainTest()
{
    // 我是谁，我在哪儿
    DumpCallerInfo();
}

private static void DumpCallerInfo(
    [CallerFilePath] string? callerFilePath = null,
    [CallerLineNumber] int? callerLineNumber = null,
    [CallerMemberName] string? callerMemberName = null
)
{
    Console.WriteLine("Caller info:");
    Console.WriteLine($@"CallerFilePath: {callerFilePath}
CallerLineNumber: {callerLineNumber}
CallerMemberName: {callerMemberName}
");
}

针对 CallerLineNumber 的类型是 int，所以参数类型需要能够直接接收 int，如上面的 [CallerLineNumber] int? callerLineNumber = null 也可以改成 [CallerLineNumber] int callerLineNumber = -1 或者 [CallerLineNumber] long callerLineNumber = -1

但是不能改成 [CallerLineNumber] string callerLineNumber = null 或者 [CallerLineNumber] short callerLineNumber = -1

string 类型不兼容，short 不能隐式转换

上面代码输出结果类似下面：

Caller info:
CallerFilePath: C:\projects\sources\SamplesInPractice\CSharp10Sample\CallerInfo.cs
CallerLineNumber: 8
CallerMemberName: MainTest

CallerArgumentExpression

CallerArgumentExpression 也是属于一种 Caller Info

下面这里是利用 CallerArgumentExpression 实现的几个验证方法，如果参数不合法就抛出一个异常，通过 CallerArgumenExpression 来自动的获取调用方的参数表达式

public static class Verify
{
    public static void Argument(bool condition, string message, [CallerArgumentExpression("condition")] string? conditionExpression = null)
    {
        if (!condition) throw new ArgumentException(message: message, paramName: conditionExpression);
    }

    public static void NotNullOrEmpty(string argument, [CallerArgumentExpression("argument")] string? argumentExpression = null)
    {
        if (string.IsNullOrEmpty(argument))
        {
            throw new ArgumentException("Can not be null or empty", argumentExpression);
        }
    }

    public static void InRange(int argument, int low, int high,
        [CallerArgumentExpression("argument")] string? argumentExpression = null,
        [CallerArgumentExpression("low")] string? lowExpression = null,
        [CallerArgumentExpression("high")] string? highExpression = null)
    {
        if (argument < low)
        {
            throw new ArgumentOutOfRangeException(paramName: argumentExpression,
                message: $"{argumentExpression} ({argument}) cannot be less than {lowExpression} ({low}).");
        }

        if (argument > high)
        {
            throw new ArgumentOutOfRangeException(paramName: argumentExpression,
                message: $"{argumentExpression} ({argument}) cannot be greater than {highExpression} ({high}).");
        }
    }

    public static void NotNull<T>(T? argument, [CallerArgumentExpression("argument")] string? argumentExpression = null)
        where T : class
    {
        ArgumentNullException.ThrowIfNull(argument, argumentExpression);
    }
}

来看一个使用调用示例：

var name = string.Empty;
InvokeHelper.TryInvoke(() => Verify.NotNullOrEmpty(name));

上面的 InvokeHelper.TryInvoke 是封装的一个方法，如果有异常会记录一个日志

上面代码执行结果如下：

可以看到我们的名称也是被记录了下来 Parameter 名字就是我们传入的变量名，不需要我们再手动的额外加一个 nameof(name) 了

再来看一个调用示例，调用代码如下：

var num = 10;
InvokeHelper.TryInvoke(() => Verify.InRange(num, 2, 5));
InvokeHelper.TryInvoke(() => Verify.InRange(num, 10 + 2, 10 + 5));

输出结果如下：

如果没有变量名或者属性名等，就会直接用传入进来的 value 字面量，如果传入进来的是一个表达式，那么记录下来的就是表达式本身，比如上面输出的 5/10 + 2，而 num 是传入的一个变量，就会获取到变量的名字，是不是很神奇，很多验证的地方就可以简化很多了

Sample

CallerArgumentExpression 有一个很典型的一个实际应用就是 .NET 6 里新增的一个 API

ArgumentNullException.ThrowIfNull() 方法，这个方法的实现如下：

/// <summary>Throws an <see cref="ArgumentNullException"/> if <paramref name="argument"/> is null.</summary>
/// <param name="argument">The reference type argument to validate as non-null.</param>
/// <param name="paramName">The name of the parameter with which <paramref name="argument"/> corresponds.</param>
public static void ThrowIfNull([NotNull] object? argument, [CallerArgumentExpression("argument")] string? paramName = null)
{
    if (argument is null)
    {
        Throw(paramName);
    }
}

[DoesNotReturn]
private static void Throw(string? paramName) =>
    throw new ArgumentNullException(paramName);

源码可以从 Github 上看 https://github.com/dotnet/runtime/blob/v6.0.0/src/libraries/System.Private.CoreLib/src/System/ArgumentNullException.cs

我们实际调用的时候就可以不传参数名，会自动的获取参数名，示例如下：

object? xiaoMing = null;
InvokeHelper.TryInvoke(() => ArgumentNullException.ThrowIfNull(xiaoMing));

输出结果如下：

从上面的结果我们可以看到，参数名已经自动的解析出来了

More

升级 .NET 6 的小伙伴快用这个改造你的代码吧，然后就是很多 null 检查也可以使用新的 ArgumentNullException.ThrowIfNull 去简化代码吧~~

想使用上述代码测试，可以从 Github 获取 https://github.com/WeihanLi/SamplesInPractice/blob/master/CSharp10Sample/CallerInfo.cs

References

• https://www.codeproject.com/Tips/606379/Caller-Info-Attributes-in-Csharp-5-0

• https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-10.0/caller-argument-expression?WT.mc_id=DT-MVP-5004222

• https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/attributes/caller-information?WT.mc_id=DT-MVP-5004222

• https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-10?WT.mc_id=DT-MVP-5004222#callerargumentexpression-attribute-diagnostics

• https://github.com/dotnet/runtime/blob/v6.0.0/src/libraries/System.Private.CoreLib/src/System/ArgumentNullException.cs

• https://github.com/WeihanLi/SamplesInPractice/blob/master/CSharp10Sample/CallerInfo.cs