.NET Framework ASP.NET WebApi 2中启用NLog AspNetBufferingWrapper方法

1. AspNetBufferingWrapper是否该使用？如何让它生效？ #

• 是否该用：是的。AspNetBufferingWrapper是专为ASP.NET（非Core）场景设计的缓冲包装器，它绑定ASP.NET请求生命周期，在请求结束时批量发送日志，同时保留请求上下文的aspnet-*属性，比通用的BufferingWrapper更适配ASP.NET环境。
• 生效步骤：
  • 安装对应.NET Framework版本的NLog.Web包（比如NLog.Web.AspNet45或NLog.Web.AspNet48），避免混用.NET Core版本的包。
  • 验证web.config的HttpModule注册：
    • IIS集成模式下，在<system.webServer>节点添加：

      <modules>
        <add name="NLog" type="NLog.Web.NLogHttpModule, NLog.Web" />
      </modules>
      

    • IIS经典模式下，在<system.web>节点添加：

      <httpModules>
        <add name="NLog" type="NLog.Web.NLogHttpModule, NLog.Web" />
      </httpModules>
      

  • 在NLog配置中用AspNetBufferingWrapper包裹目标（比如Elasticsearch），示例：

    <targets>
      <target name="elastic" type="Elasticsearch" uri="http://your-es-server:9200">
        <layout type="JsonLayout">
          <attribute name="requestUrl" layout="${aspnet-request-url}" />
        </layout>
      </target>
      <target name="bufferedElastic" type="AspNetBufferingWrapper" target="elastic" flushTimeout="5000" bufferSize="100">
      </target>
    </targets>
    <rules>
      <logger name="*" minlevel="Info" writeTo="bufferedElastic" />
    </rules>
    

  • 确保NLog默认启用的ASP.NET上下文功能未被手动关闭。

2. 应采用的配置选项及包 #

必备包 #

• NLog.Web：核心依赖，提供AspNetBufferingWrapper和aspnet-*渲染器，负责绑定ASP.NET请求上下文。
• NLog.Targets.Elasticsearch：若需输出到Elasticsearch，安装此包（注意版本与NLog.Web兼容）。
• NLog.Owin.Logging（仅OWIN集成场景）：用于在OWIN管道中捕获请求上下文，需在Startup类中注册：

  using NLog.Owin.Logging;
  public void Configuration(IAppBuilder app)
  {
      // 注册NLog中间件，需放在WebApi配置之前
      app.UseNLog();
      // 后续OWIN/WebApi配置
      var config = new HttpConfiguration();
      config.MapHttpAttributeRoutes();
      app.UseWebApi(config);
  }
  

关键配置选项 #

• AspNetBufferingWrapper常用属性：
  • target：指定要包裹的目标名称（如Elasticsearch目标）。
  • flushTimeout：缓冲超时时间，到期自动发送日志（单位毫秒）。
  • bufferSize：最大缓冲条数，达到阈值时自动触发发送。
• 在目标的布局中明确配置aspnet-*属性，比如Elasticsearch的JsonLayout：

  <layout type="JsonLayout">
    <attribute name="requestUrl" layout="${aspnet-request-url}" />
    <attribute name="userName" layout="${aspnet-user-identity}" />
    <attribute name="controller" layout="${aspnet-mvc-controller}" />
  </layout>
  

3. 为何BufferingWrapper无法传递aspnet-*属性？ #

通用的BufferingWrapper是全局缓冲机制，不依赖ASP.NET请求生命周期，也不会关联请求上下文的作用域。aspnet-*属性的值存储在当前请求的HttpContext对应的NLog作用域中，当BufferingWrapper缓冲日志时，可能已脱离原请求上下文（比如请求结束后HttpContext被回收），或未捕获请求作用域内的属性，导致渲染aspnet-*时无法获取有效值。

而AspNetBufferingWrapper会绑定到ASP.NET的EndRequest事件，在请求即将结束时处理缓冲日志，此时请求上下文仍可用，能正确读取aspnet-*属性的值，因此可以将这些属性传递到目标（如Elasticsearch）。

内容的提问来源于stack exchange，提问作者Artem Grunin