NLog文章系列——如何写自定义布局生成器（Layout Renderer）

作者：Jarosław Kowalski <jaak@jkowalski.net>

翻译：CrazyCoder（由衷感谢他的热心！！）

原文：http://www.nlog-project.org/howto_write_layout_renderer.html

更多关于NLog的中文文章，请参考《NLog文章系列》。

 

为什么需要写自定义布局生成器？

布局生成器能够输出程序的环境信息，因此能够记录更加丰富的调试信息。NLog为一些最常用的任务（如输出环境变量、注册表、线程id、程序根目录等）设计了布局生成器。不过由于应用程序和框架各不相同，还是有必要开发自定义的布局生成器。

 

如何写

只需要建立一个继承自NLog.LayoutRenderer的类并重载Append()方法，在该方法中调用ApplyPadding()，这样就可以得到按照已有布局生成器生成的格式化文本并送给产生最终输出的StringBuilder。

 

例子

下面是一个输出当前小时时间的布局生成器的框架代码。编译命令为：

csc.exe /t:library /out:MyAssembly.dll /r:NLog.dll MyFirstLayoutRenderer.cs

 

using System;
using System.Text;

using NLog;

namespace MyNamespace
{
    [LayoutRenderer("hour")]
    public sealed class HourLayoutRenderer: LayoutRenderer
    {
        private bool _showMinutes = false;

        // 一个配置参数的示例
        public bool ShowMinutes
        {
            get { return _showMinutes; }
            set { _showMinutes = value; }

        }
        protected override int GetEstimatedBufferSize(LogEventInfo ev)
        {
            // 最多需要两位字符表示小时数
            // 返回本布局生成器需要的缓冲区数
            return 2;
        }

        protected override void Append(StringBuilder builder, LogEventInfo ev)
        {
            // 得到当前的小时或分钟数并转为字符串，格式化
            // 最终添加给指定的StringBuilder
            if (ShowMinutes)
            {
                builder.Append(ApplyPadding(DateTime.Now.Minute.ToString()));
            }
            else
            {
                builder.Append(ApplyPadding(DateTime.Now.Hour.ToString()));
            }
        }
    }
}

 

 

如何使用自定义布局生成器

把生成器编译到一个动态链接库并在配置文件的<extensions />区域中引用它，具体用法请参考这里。

 

配置文件的例子

下面的例子能够在所有日志之前加上系统当前的小时信息。的确很简单吧？

 

<nlog>
  <extensions>
    <add assembly="MyAssembly"/>
  </extensions>
  <targets>
    <target name="console" type="Console"
            layout="${hour:showminutes=false} ${message}"/>
  </targets>
  <rules>
    <logger name="*" minLevel="Info" appendTo="console"/>
  </rules>
</nlog>

 

如何传递配置参数

看一下上面的例子，“ShowMinutes”这个属性就是一个配置参数。只需在类中声明公有属性来保存配置参数就可以了。参数中间以以冒号分隔，如：

${hour:showminutes=true}

这样在加载配置信息时就会把ShowMinutes属性的值设置为true。传递多个参数值需要用冒号逐一分开：

${layoutrenderername:par1=value1:par2=value2:par3=value3:...:parN=valueN}

NLog支持integer，string，datetime和boolean类型的参数并会对类型进行自动转换。

 

必须要放在新的动态链接库里吗？

完全不需要。你可以在程序中调用LayoutRendererFactory.AddLayoutRenderer()方法注册你的布局生成器。不过必须保证注册完成之前不能记录任何日志信息。在<extensions />区域参照EXE可执行文件是允许的。

static void Main(string[] args)
{
    LayoutRendererFactory.AddLayoutRenderer("hour", typeof(MyNamespace.MyFirstLayoutRenderer));

    // start logging here
}

 

Last updated: 2006-07-10 11:32:55