NLog文章系列——如何编写自定义的过滤器（Filter）

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

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

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

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

 

为什么要编写自定义过滤器？

过滤器的作用就是减少向日志目标输出不需要的日志信息。NLog提供一些预定义的过滤器，这些过滤器支持大多数常用的字符串运算符。如果这些预定义的过滤器不符合你的需求，那就自己动手吧。

 

怎样编写？

写一个过滤器并不复杂。写一个继承了NLog.Filter的类并重写其中的Check()方法就可以了。Check()方法的返回值包括：

1. FilterResult.Neutral – 该过滤器不想决定这个消息是否应被记录。其它的过滤器（如果有的话）可以进一步检查。
2. FilterResult.Ignore – 这个消息不应该被记录。
3. FilterResult.Log – 这个消息应该被记录。也不需要其它过滤器的进一步检查。

通常即使一个消息符合过滤条件，也应该让用户来决定这个消息是否应当被过滤。这种情况下如果符合过滤条件滤器都应当返回Result。如果过滤器要支持用户自定义配置那么应该返回Result或者FilterResult.Neutral。

 

例子

这个例子里介于两个特定时间之间记录的日志信息会被过滤。

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

 

using System;
using System.Text;

using NLog;

namespace MyNamespace
{
    [Filter("hourRange")]
    public sealed class HourRangeFilter: Filter
    {
        private int _fromHour = 0;
        private int _toHour = -1;

        public int FromHour
        {
            get { return _fromHour; }
            set { _fromHour = value; }

        }
        public int ToHour
        {
            get { return _toHour; }
            set { _toHour = value; }

        }

        protected override FilterResult Check(LogEventInfo ev)
        {
            if (ev.TimeStamp.Hour >= FromHour && ev.TimeStamp.Hour <= ToHour)
                return Result;
            else
                return FilterResult.Neutral;
        }
    }
}

 

如何使用自定义过滤器

只要把自定义过滤器所在的动态链接库引用到配置文件的<extensions />区域即可，具体做法请参考这里。

 

配置文件的例子

这个配置文件设置过滤在10:00和12:59之间记录的日志。很简单吧。

<nlog>
  <extensions>
    <add assembly="MyAssembly"/>
  </extensions>
  <targets>
    <target name="console" type="Console"/>
  </targets>
  <rules>
    <logger name="*" minLevel="Info" appendTo="console">
      <filters>
        <hourRange fromHour="10" toHour="12" action="Ignore"/>
      </filters>
    </logger>
  </rules>
</nlog>

怎样将配置参数传递给过滤器

看一下上面的例子，“FromHour”和“ToHour”这个两个属性就是两个配置参数。只需在类中声明公有属性来保存配置参数就可以了。过滤器配置中的每一个参数都会被传递给正确的公有属性。NLog支持integer，string，datetime和boolean类型的参数并会对类型进行自动转换。参数都是大小写敏感的。

<filters> ... <hourRange fromHour="10" toHour="12" action="Ignore" /> ... </filters>

这里在配置过滤器的时候FromHour的值被设为10，ToHour的值被设为12。可以使用更多的参数来传递更多的属性：

<filters> ... <hourRange p1="" p2="" p3="" p4="" pN="" action="Ignore" /> ... </filters>

 

需要一个专门的动态链接库吗？

完全不必。可以调用FilterFactory.AddFilter()来通过程序注册过滤器。不过必须保证注册完成之前不能记录任何日志信息。在<extensions />区域参照EXE可执行文件是允许的。

static void Main(string[] args)
{
    FilterFactory.AddFilter("MyFirst", typeof(MyNamespace.MyFirstFilter));

    // start logging here
}

 

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