Serilog.Formatting.Log4Net 1.1.0

Serilog.Formatting.Log4Net 是 Serilog 的一个附加组件，可以将日志事件格式化为与 log4net 或 log4j 兼容的 XML 格式。

您可以使用 Log4View 来查看此格式器生成的日志文件。

入门

使用 NuGet 包管理器将 Serilog.Formatting.Log4Net NuGet 包添加到您的项目中，或运行以下命令：

dotnet add package Serilog.Formatting.Log4Net

Serilog.Formatting.Log4Net 提供了实现 Serilog 的 ITextFormatter 接口的 Log4NetTextFormatter 类。

下面是如何在简单的 Hello World 应用中使用该类的示例：

using System;
using Serilog;
using Serilog.Formatting.Log4Net;

static class Program
{
    static void Main(string[] args)
    {
        var logger = new LoggerConfiguration()
            .Enrich.WithProperty("AppName", "Program")
            .WriteTo.File(new Log4NetTextFormatter(c => c.UseCDataMode(CDataMode.Never)), "logs.xml")
            .CreateLogger();

        logger.Information("Start app with {Args}", args);
        Console.WriteLine("Hello World!");
        logger.Information("Stop app");
    }
}

运行此应用程序会将以下XML事件写入当前工作目录中的 logs.xml 文件

<log4net:event timestamp="2021-02-24T18:23:40.4496605+01:00" level="INFO" xmlns:log4net="https://logging.apache.ac.cn/log4net/schemas/log4net-events-1.2/">
  <log4net:properties>
    <log4net:data name="Args[0]" value="--first-argument" />
    <log4net:data name="Args[1]" value="--second-argument" />
    <log4net:data name="AppName" value="Program" />
  </log4net:properties>
  <log4net:message>Start app with ["--first-argument", "--second-argument"]</log4net:message>
</log4net:event>
<log4net:event timestamp="2021-02-24T18:23:40.5086666+01:00" level="INFO" xmlns:log4net="https://logging.apache.ac.cn/log4net/schemas/log4net-events-1.2/">
  <log4net:properties>
    <log4net:data name="AppName" value="Program" />
  </log4net:properties>
  <log4net:message>Stop app</log4net:message>
</log4net:event>

配置

您可以通过多种方式配置 Log4NetTextFormatter，流畅的选项构建器将帮助您发现所有可能性。

异常格式化

默认情况下，Log4NetTextFormatter 通过调用 ToString() 来格式化异常。您可以设置自己的格式化委托来自定义此行为。例如，您可以像这样使用 Ben.Demystifier

new Log4NetTextFormatter(c => c.UseExceptionFormatter(exception => exception.ToStringDemystified()))

CDATA

默认情况下，Log4NetTextFormatter 用 CDATA 部分写入所有消息和异常。您可以使用 CDataMode.IfNeeded 将其配置为仅在消息或异常包含 &、< 或 > 时使用 CDATA 部分或使用 CDataMode.Never 来永远不写入 CDATA 部分

new Log4NetTextFormatter(c => c.UseCDataMode(CDataMode.Never))

XML 名称空间

您可以通过在选项构建器上调用 UseNoXmlNamespace() 来删除 log4net XML 名称空间。如果您想节省一些字节数，并且日志读取器支持没有名称空间的 log4net XML 事件，这非常有用，例如 Log4View 就这样做。

new Log4NetTextFormatter(c => c.UseNoXmlNamespace())

换行符

默认情况下，Log4NetTextFormatter 使用行换行符 (LF) 字符作为 XML 元素之间的换行符。如果需要，您可以选择使用 CRLF

new Log4NetTextFormatter(c => c.UseLineEnding(LineEnding.CarriageReturn | LineEnding.LineFeed))

缩进

默认情况下，Log4NetTextFormatter 使用两个空格缩进 XML 元素。您可以将其配置为使用空格或制表符。例如，使用一个制表符缩进 XML 元素

new Log4NetTextFormatter(c => c.UseIndentationSettings(new IndentationSettings(Indentation.Tab, 1)))

或者您可以使用不进行缩进，使 log4net 事件在单行中写入

new Log4NetTextFormatter(c => c.UseNoIndentation())

格式提供者

默认情况下，Log4NetTextFormatter 当格式化实现 IFormattable 接口的 Serilog 属性时使用不变文化（Serilog 的默认值）。它可以配置为使用文化特定的格式化信息。例如，使用瑞士法语文化

new Log4NetTextFormatter(c => c.UseFormatProvider(CultureInfo.GetCultureInfo("fr-CH")))

属性过滤器

默认情况下，Log4NetTextFormatter 序列化所有 Serilog 属性。您可以通过配置自定义属性过滤器委托来过滤一些属性

new Log4NetTextFormatter(c => c.UsePropertyFilter((_, name) => name != "MySecretProperty"))

Log4j 兼容模式

格式化程序还支持 log4j 兼容模式。Log4Net 和 Log4j XML 格式非常相似，但有一些关键差异。

• event 元素在不同的 XML 名称空间中
• timestamp 属性是毫秒数（log4j）与 ISO 8061 格式的日期（log4net）
• 异常元素命名为 throwable 与 exception

为了启用兼容模式，请调用 UseLog4JCompatibility()

new Log4NetTextFormatter(c => c.UseLog4JCompatibility())

请注意，与其他流畅配置方法不同，此方法不能链式调用，因为您不应该在启用 log4j 兼容模式后更改选项。

或者，您可以使用配置为 log4j XML 布局的静态属性 Log4NetTextFormatter.Log4JFormatter。此静态属性在使用 Serilog.Settings.Configuration 包时也很有用，可以使用以下访问器使用

Serilog.Formatting.Log4Net.Log4NetTextFormatter::Log4JFormatter, Serilog.Formatting.Log4Net

组合选项

您还可以组合选项，例如，使用 Ben.Demystifier 进行异常格式化、过滤属性和使用 log4j 兼容模式。此示例配置在网络中使用 Serilog.Sinks.Udp 发送日志，并可以通过 Loginator 查看

var appFileName = Path.GetFileName(Environment.GetCommandLineArgs()[0]);
var processId = Process.GetCurrentProcess().Id;
var formatter = new Log4NetTextFormatter(c => c
    .UseExceptionFormatter(exception => exception.ToStringDemystified())
    .UsePropertyFilter((_, name) => name.StartsWith("log4j"))
    .UseLog4JCompatibility()
);
Log.Logger = new LoggerConfiguration()
    .Enrich.WithProperty("log4japp", $"{appFileName}({processId})")
    .Enrich.WithProperty("log4jmachinename", Environment.MachineName)
    .Enrich.WithThreadId()
    .WriteTo.Udp("localhost", 7071, AddressFamily.InterNetwork, formatter)
    .CreateLogger();

增强器

log4Net XML格式定义了一些特殊属性，这些属性默认不包含在Serilog事件中。可以通过使用合适的Serilog 增强器来添加它们。

线程ID

通过使用Serilog.Enrichers.Thread将线程ID包含到log4net事件中

var loggerConfiguration = new LoggerConfiguration().Enrich.WithThreadId();

域名和用户名

通过使用Serilog.Enrichers.Environment将域名和用户名包含到log4net事件中

var loggerConfiguration = new LoggerConfiguration().Enrich.WithEnvironmentUserName();

机器名

通过使用Serilog.Enrichers.Environment将机器名包含到log4net事件中

var loggerConfiguration = new LoggerConfiguration().Enrich.WithMachineName();

调用者

通过使用Serilog.Enrichers.WithCaller包含调用者信息（类、方法、文件、行）

var loggerConfiguration = new LoggerConfiguration().Enrich.WithCaller(includeFileInfo: true);

全部整合

结合这四个增强器会产生一个包含thread、domain和username属性的日志事件，包含包含机器名的log4net:HostName属性和一个locationInfo元素

<event timestamp="2020-06-28T10:07:33.314159+02:00" level="INFO" thread="1" domain="TheDomainName" username="TheUserName">
  <properties>
    <data name="log4net:HostName" value="TheMachineName" />
  </properties>
  <message>The message</message>
  <locationInfo class="Program" method="Main(System.String[])" file="/Absolute/Path/To/Program.cs" line="29" />
</event>

相关项目

Serilog.Sinks.Log4Net项目与之一致，但依赖于log4net NuGet包，而Serilog.Formatting.Log4Net则不是。此外，Serilog.Sinks.Log4Net是一个收集器，因此除了配置Serilog外还必须配置log4net。

Serilog.Sinks.Udp项目也提供了一个Log4Net格式化器，但它手动（不使用XmlWriter）写入XML，完全忽略Serilog属性，完全没有可配置性（缩进、换行符、命名空间等），且无文档记录。