Serilog 源码解析——数据的保存（中）

上一篇文章中揭露了日志数据的绑定逻辑，主要说明了日志数据绑定的结果信息，即EventProperty结构体和LogEventProperty类，以及日志数据与具名属性Token的绑定类PropertyBinder。在本文中，我们主要对PropertyValueConverter类及其涉及的其他相关类进行说明。关注的重点在如何利用具名属性 Token 以及对应的日志数据来构造对应的LogEventPropertyValue类对象。（系列目录）

PropertyValueConverter类

PropertyValueConverter类是一个非常复杂的类。Serilog将其分成两个代码文件存储，分别为./Capturing/PropertyValueConverter.cs以及./Capturing/DepthLimiter.cs文件。先看下PropertyValueConverter有什么字段和属性。

partial class PropertyValueConverter : ILogEventPropertyFactory, ILogEventPropertyValueFactory
{
    readonly IDestructuringPolicy[] _destructuringPolicies;
    readonly IScalarConversionPolicy[] _scalarConversionPolicies;
    readonly DepthLimiter _depthLimiter;
    readonly int _maximumStringLength;
    readonly int _maximumCollectionCount;
    readonly bool _propagateExceptions;
    ...
}

好家伙，一次性来了一大堆第一次见的玩意。一个个看，一个个猜，先弄懂大意再说。

ILogEventPropertyFactory和ILogEventPropertyValueFactory接口

首先就是ILogEventPropertyFactory和ILogEventPropertyValueFactory接口，从Factory名称大概猜出来，属于工厂模式的一种设计，是构造对应的LogEventProperty和LogEventPropertyValue对象。这些接口位于./Core文件夹内部，表明是非常重要的接口。

public interface ILogEventPropertyValueFactory
{
    LogEventPropertyValue CreatePropertyValue(object value, bool destructureObjects = false);
}

public interface ILogEventPropertyFactory
{
    LogEventProperty CreateProperty(string name, object value, bool destructureObjects = false);
}

从函数签名上看，基本和猜测一致，用于构建对应的对象，最后一个输入参数指明是否以解构对象的方式进行构建。

IDestructuringPolicy和IScalarConversionPolicy接口

在PropertyValueConverter类中，还保有对IDestructuringPolicy和IScalarConversionPolicy接口数组的引用。字面意义上，这两个接口均描述的是一个策略，且保存在./Core文件夹下。这两个接口有什么用，做什么，先看下代码吧。

public interface IDestructuringPolicy
{
    bool TryDestructure(object value, ILogEventPropertyValueFactory propertyValueFactory, out LogEventPropertyValue result);
}
public interface IScalarConversionPolicy
{
    bool TryConvertToScalar(object value, out ScalarValue result);
}

从这两个接口内的函数签名可以猜测出它们分别将日志数据转化成对应的数据类型。bool返回值标注该转换是否成功，输入参数中被 out 修饰的变量则可以看成是转换成功后的结果变量。以此，可以发现，IDestrucuringPolicy接口用于将数据转换成LogEventPropertyValue对象，而IScalarConversionPolicy接口则将数据转换成ScalarValue。

DepthLimiter类

DepthLimiter类对象是ProertyValueConverter所持有的最后一个复杂的类对象。有意思的是，该类的作用范围放在PropertyValueConverter类的内部。换句话来说，就是DepthLimiter是PropertyValueConveter的内部类。

class DepthLimiter : ILogEventPropertyValueFactory
{
    [ThreadStatic]
    static int _currentDepth;
    readonly int _maximumDestructingDepth;
    readonly PropertyValueConverter _propertyValueConverter;

    public static void SetCurrentDepth(int depth)
    {
        _currentDepth = depth;
    }
    public LogEventPropertyValue CreatePropertyValue(object value, Destructuring destructuring)
    {
        var storedDepth = _currentDepth;

        var result = DefaultIfMaximumDepth(storedDepth) ??
            _propertyValueConverter.CreatePropertyValue(value, destructuring, storedDepth + 1);

        _currentDepth = storedDepth;

        return result;
    }
    ...
}

可以看到，DepthLimiter也是一个处理日志消息数据与LogEventPropertyValue相绑定的过程类。和PropertyValueConverter类一样，它也继承于ILogEventPropertyValueFactory接口。然而，DepthLimiter和PropertyValueConverter不同之处在于：

1. DepthLimiter只负责对LogEventPropertyValue的创建，而PropertyValueConveter不仅负责前者的构建，还负责对LogEventProperty的创建，这一点从所继承的接口数目可以看出来。也就是说，PropertyValueConverter的作用范围比DepthLimiter大。
2. DepthLimiter类不负责具体的构建，这一点可以从其包含_propertyValueConverter字段可以看出来，具体对日志数据的渲染还是交给内部的PropertyValueConverter类对象来处理。那么DepthLimiter负责什么呢？它负责记录处理的深度，这一点从_currentDepth这个变量可以看出来。

考虑这样一个数据:

class A
{
    public B B { get; }
}

class B
{
    public int C { get; }
}

数据A具有非常复杂的形式，A 中有 B 的属性，B 内有int类型的C属性，一共三层。最外层为 A，最内层为 C。如果采用解构的方式记录数据 A 的对象，那么需要深入 3 层迭代转换。比如说C数据应该放在ScalarValue中，B和A应该放在StructValue中。Serilog通过PropertyValueConverter和DepthLimiter的相互引用配合达到递归转换的目的。也就是说，DepthLimiter负责维护递归转换时当前转换数据所处的深度。

剩余参数

在PropertyValueConverter中，还剩下一些较为简单的数据参数。在了解了DepthLimiter之后，剩余的三个参数可以很明显看出来。

• _maximumStringLength：指的是构造日志信息字符串的最大长度
• _maximumCollectionCount: 指的是日志数据集合解析的最大个数
• _propgateExceptions: 该值是一个bool类型，表示在保存日志数据的过程中，若发生了异常，则相关异常是否被抛出。

接口函数

接下来，我们把注意力再回到PropertyValueConverter类中对IDestructuringPolicy和IScalarConversionPolicy接口函数实现的部分。

public LogEventProperty CreateProperty(string name, object value, bool destructureObjects = false)
{
    return new LogEventProperty(name, CreatePropertyValue(value, destructureObjects));
}

public LogEventPropertyValue CreatePropertyValue(object value, bool destructureObjects = false)
{
    return CreatePropertyValue(value, destructureObjects, 1);
}

可以看到，无论是哪种接口，其内部直接或间接在调用CreatePropertyValue(object value, Destructuring destructuring, int depth)函数（类文件中第126行）。下面是该函数的核心部分代码。

LogEventPropertyValue CreatePropertyValue(object value, Destructuring destructuring, int depth)
{
    if (value == null)
      return new ScalarValue(null);
    ...
    // ScalarValue的转换策略
    foreach (var scalarConversionPolicy in _scalarConversionPolicies)
    {
        if (scalarConversionPolicy.TryConvertToScalar(value, out var converted))
            return converted;
    }

    // 设置深度
    DepthLimiter.SetCurrentDepth(depth);
    // 如果Token采用解构渲染，则使用解构策略尝试解析数据
    if (destructuring == Destructuring.Destructure)
    {
        foreach (var destructuringPolicy in _destructuringPolicies)
        {
            if (destructuringPolicy.TryDestructure(value, _depthLimiter, out var result))
                return result;
        }
    }
    // 获取日志数据的数据类型，利用内置的解析策略对其解析
    var valueType = value.GetType();
    if (TryConvertEnumerable(value, destructuring, valueType, out var enumerableResult))
        return enumerableResult;
    if (TryConvertValueTuple(value, destructuring, valueType, out var tupleResult))
        return tupleResult;
    if (TryConvertCompilerGeneratedType(value, destructuring, valueType, out var compilerGeneratedResult))
        return compilerGeneratedResult;
    // 如果以上策略都不满足的话，直接构造
    return new ScalarValue(value.ToString());
}

这个函数非常复杂，但大体上分成以下几个步骤。

1. 如果传入的数据是一个null对象，则直接使用ScalarValue构造。
2. 利用内部保存的IScalarConversionPolicy数组尝试对日志数据绑定，如果能绑定，则将结果返回，否则继续。
3. 设置深度值，之所以将深度值放在这里设置，是因为后续操作可能会用到这个深度值。
4. 利用内部维护的IDestructingPolicy数组尝试对日志数据绑定，如果能绑定，则返回结果值，否则继续。
5. 获取当前日志数据的类型，并采用3个内置的绑定规则进行绑定。如果能成功，则返回结果值，如果所有都无法成功，则认为该对象无法在现有的规则下绑定，则采用ScalarValue对其绑定。

第一步好理解，如果值为空，则直接采用ScalarValue对其渲染，ScalarValue会将其渲染成null。之所以不返回null对象，则是尝试对null操作调用函数等操作会抛出异常，而如果在调用前编写判断的逻辑会大大干扰程序员编写代码的逻辑。因此，直接使用new ScalarValue(null)会更加方便，不易出错。

第二步则是利用多个IScalarConversionPolicy策略类将传入的日志对象数据尝试转换成ScalarValue对象，一旦某个策略能够成功转换，那么直接跳出。

第三步和第四步的作用是尝试利用IDestructuringPolicy策略类对输入的日志数据进行转换。该部分将日志数据按照策略的要求尝试转换成LogEventPropertyValue类对象，和之前一样，一旦某个策略成功，则直接跳出。Serilog中定义了一组相关策略，其类代码保存在./Policies文件夹中。

最后，如果以上所有策略都没法满足时，则尝试采用内置的策略。

总结

总的来说，当记录日志时，其所附带的日志数据通过PropertyValueConverter类对象将其转化成一系列的LogEventPropertyValue对象，最终变成LogEventProperty对象。这些对象有着不同的语义，在渲染的行为方式上表现有所不同，比如说ScalarValue表示的一个原始数据，它采用ToString的方法对数据进行渲染；SequenceValue表示一类数组，采用[]方式对其渲染；DictionaryValue表示一组键值对，采用{}方式对其渲染；StructureValue表示一个复杂且需要解构的日志数据对象，采用{}方式渲染。除此之外，PropertyValueConverter还包含一个内部类DepthLimiter，该类是对PropertyValueConverter类的进一步装饰，让数据的解析添加了深度信息。在下一篇中，我们进一步来看IScalarConversionPolicy、IDestructuringPolicy以及它们的实现类。