log4net 進階配置詳解（二）：Layout、Filter、配置文件結構與程式化配置

Layout：日誌輸出格式化的核心

Layout 決定日誌事件最終輸出的文本格式。每個 Appender 僅能關聯一個 Layout。自訂 Layout 需繼承 log4net.Layout.LayoutSkeleton 並實作 ILayout。

內建 Layout 類型

PatternLayout 轉換模式完整參考

<layout type="log4net.Layout.PatternLayout">
  <param name="ConversionPattern" value="%date [%thread] %-5level %logger [%property{NDC}] - %message%newline" />
</layout>

Filter：精準控制日誌流向

Filter 掛載在 Appender 之下，按定義順序鏈式過濾。常用內建 Filter：

1. LevelRangeFilter —— 級別範圍過濾

<filter type="log4net.Filter.LevelRangeFilter">
  <param name="LevelMin" value="INFO" />
  <param name="LevelMax" value="WARN" />
</filter>

僅允許 `INFO`、`WARN` 通過，`DEBUG` 被丟棄，`ERROR`/`FATAL` 也被丟棄（因超出 Max）。

2. LevelMatchFilter —— 精確級別匹配

<filter type="log4net.Filter.LevelMatchFilter">
  <param name="LevelToMatch" value="ERROR" />
  <param name="AcceptOnMatch" value="true" />
</filter>
<filter type="log4net.Filter.DenyAllFilter" /> <!-- 關鍵：拒絕所有其他 -->

組合 `DenyAllFilter` 實現「僅記錄 ERROR」效果。

3. StringMatchFilter / RegexFilter —— 內容過濾

<filter type="log4net.Filter.StringMatchFilter">
  <param name="StringToMatch" value="Password" />
  <param name="AcceptOnMatch" value="false" /> <!-- 包含密碼的日誌直接丟棄 -->
</filter>

4. PropertyFilter / LoggerMatchFilter

基於 MDC/NDC 屬性或 Logger 名稱過濾，支援多租戶、多模塊日誌路由。

配置文件完整結構解析

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="log4net" 
             type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" />
  </configSections>

  <log4net>
    <!-- 根 Logger：所有 Logger 的最終 fallback -->
    <root>
      <level value="WARN" /> <!-- 根級別閾值 -->
      <appender-ref ref="FileAppender" />
      <appender-ref ref="ConsoleAppender" />
    </root>

    <!-- 特定 Logger：覆蓋根配置 -->
    <logger name="MyApp.Data" additivity="false"> <!-- additivity=false 斷開向根傳遞 -->
      <level value="DEBUG" />
      <appender-ref ref="SqlAppender" />
    </logger>

    <!-- Appender 定義 -->
    <appender name="FileAppender" type="log4net.Appender.RollingFileAppender">
      <param name="File" value="logs/app.log" />
      <param name="AppendToFile" value="true" />
      <param name="RollingStyle" value="Composite" /> <!-- 按大小+日期滾動 -->
      <param name="MaxSizeRollBackups" value="10" />
      <param name="MaximumFileSize" value="10MB" />
      <param name="DatePattern" value="yyyyMMdd" />
      <layout type="log4net.Layout.PatternLayout">
        <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n" />
      </layout>
      <filter type="log4net.Filter.LevelRangeFilter">
        <param name="LevelMin" value="INFO" />
        <param name="LevelMax" value="FATAL" />
      </filter>
    </appender>

    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
      <layout type="log4net.Layout.PatternLayout">
        <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n" />
      </layout>
    </appender>
  </log4net>
</configuration>

關鍵屬性說明

• additivity="false"：阻斷該 Logger 向祖先（根）傳遞日誌事件，避免重複寫入。
• RollingFileAppender 參數：`RollingStyle` 可為 `Size`、`Date`、`Composite`、`Once`。
• LevelMin/Max：包含邊界，即 `Min ≤ Level ≤ Max` 通過。

啟用配置的三種方式

1. Assembly 屬性（推薦，Web/桌面通用）

[assembly: log4net.Config.XmlConfigurator(ConfigFile = "log4net.config", Watch = true)]
// 放在 AssemblyInfo.cs 或 Program.cs 頂部

• Watch=true：啟用 `FileSystemWatcher`，配置文件變更自動重載，**無需重啟應用**。
• ConfigFile 與 ConfigFileExtension 二擇一。

2. 代碼啟用（動態決定配置路徑）

var repo = LogManager.GetRepository(Assembly.GetEntryAssembly());
XmlConfigurator.Configure(repo, new FileInfo("config/log4net.prod.xml"));
// 或監視變更
XmlConfigurator.ConfigureAndWatch(repo, new FileInfo("config/log4net.xml"));

3. 程式化配置（無配置文件，適合簡單工具/測試）

// 單一 Appender + PatternLayout
BasicConfigurator.Configure(
    new RollingFileAppender {
        File = "app.log",
        AppendToFile = true,
        RollingStyle = RollingFileAppender.RollingMode.Composite,
        MaxSizeRollBackups = 5,
        MaximumFileSize = "5MB",
        Layout = new PatternLayout("%d [%t] %-5p %c - %m%n")
    }
);

// 僅控制台輸出
BasicConfigurator.Configure(new ConsoleAppender {
    Layout = new PatternLayout("%d [%t] %-5p %c - %m%n")
});

限制：程式化配置僅作用於根 Logger，無法精細控制各模塊級別。

代碼中使用 Logger 的最佳實踐

public class OrderService {
    // 靜態唯讀，按類名建立 Logger，層級結構自動對應配置
    private static readonly ILog Log = LogManager.GetLogger(typeof(OrderService));

    public void PlaceOrder(Order order) {
        // 1. 級別檢查避免字串構建開銷（高頻調用關鍵）
        if (Log.IsDebugEnabled) 
            Log.Debug($"訂單詳情：{JsonSerializer.Serialize(order)}");

        try {
            _repository.Save(order);
            Log.Info($"訂單建立成功：{order.Id}");
        }
        catch (Exception ex) {
            // 2. 結構化異常記錄，保留堆疊
            Log.Error($"建立訂單失敗：{order.Id}", ex);
            throw;
        }
    }
}

總結：生產環境配置清單

1. 使用 獨立 `log4net.config` + `Watch=true`，支援熱更新。
2. 根級別設為 WARN，業務模塊 Logger 覆蓋為 INFO/DEBUG。
3. 所有 FileAppender 改用 RollingFileAppender，配置大小+日期滾動，防止磁盤寫滿。
4. 關鍵 Appender 加裝 LevelRangeFilter，錯誤日誌單獨寫入錯誤檔，便於告警掃描。
5. 敏感字段（密碼、Token、PII）在代碼層面脫敏，**或**配置 `StringMatchFilter` 二次攔截。
6. 高併發場景考慮 AsyncAppender（緩衝隊列 + 專用線程寫入），降低業務線程阻塞。