log4net 入門指南（一）：核心架構、安裝、Logger、Appender 與級別體系

什麼是 log4net？

log4net 是 Apache Logging Services 專案的 .NET 移植版，源自經典的 Java log4j。它是一個**高效、靈活、分級**的日誌框架，支援多種輸出目標（控制台、文件、資料庫、網絡、事件日誌等），並通過外部配置文件實現**零代碼修改**調整日誌行為。

核心優勢

• 運行時零干預：部署後無需重啟/重編譯即可調整級別、輸出目標、格式。
• 分級控制：按命名空間/類精細控制 `DEBUG`/`INFO`/`WARN`/`ERROR`/`FATAL`。
• 高效能：級別檢查在字串構建前，避免無效字串拼接開銷；支援非同步寫入。
• 結構化輸出：XML/JSON 格式便於 ELK、Splunk 等平台採集分析。
• 成熟穩定：超過 15 年生產驗證，.NET 生態標準日誌組件之一。

安裝與引用

// NuGet (推薦)
Install-Package log4net

// 或 .NET CLI
dotnet add package log4net

引用後，專案會包含 `log4net.dll`。源碼可從 官網 獲取。

核心架構四大組件

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Logger    │────▶│  Appender   │────▶│   Layout    │────▶│  Output     │
│  (記錄器)   │     │  (附著器)   │     │  (佈局器)   │     │  (輸出端)   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       ▲                   ▲                   ▲
       │                   │                   │
       │            ┌──────┴──────┐            │
       │            │   Filter    │            │
       │            │  (過濾器)   │            │
       │            └─────────────┘            │
       │                                       │
       └─────────────── Repository (庫) ◀──────┘
              (Logger 階層管理、配置存儲)

1. Logger (記錄器) —— 應用程序交互入口

• 通過 `LogManager.GetLogger(name)` 獲取/創建，名稱通常為類全名（`typeof(MyClass)`）。
• **層級結構**：名稱以點分隔，`MyApp.Service` 是 `MyApp.Service.User` 的祖先，自動繼承祖先配置。
• 實作 `ILog` 介面，提供五大級別方法：`Debug`、`Info`、`Warn`、`Error`、`Fatal`，各含 `Exception` 重載。
• **效能關鍵**：`IsDebugEnabled` 等布爾屬性，**必須**在高頻調用前檢查，避免字串插值/拼接浪費。

2. Repository (庫) —— 內部管理中樞

• 維護 Logger 階層樹、配置狀態、Appender 映射。
• 預設實現 `Hierarchy`（`log4net.Repository.Hierarchy`）。
• 應用層極少直接操作，由 `LogManager` 統一管理。

3. Appender (附著器) —— 輸出目的地

一個 Logger 可掛載多個 Appender，實現「一份日誌，多地輸出」。常用內建類型：

4. Layout (佈局器) —— 格式化輸出

• 將 `LoggingEvent` 格式化為文本/XML/JSON。
• 每個 Appender **僅能** 關聯一個 Layout。
• 主流：`PatternLayout`（模式字串）、`XmlLayout`、`JsonLayout`（需擴展包）。

日誌級別體系（由低到高）

級別判斷規則：`Logger.Level ≤ Message.Level` 才輸出。例如 Logger 設 `INFO`，則 `DEBUG` 被過濾，`INFO`/`WARN`/`ERROR`/`FATAL` 輸出。

快速上手：最小化配置

1. 添加配置文件 `log4net.config`

<?xml version="1.0" encoding="utf-8"?>
<log4net>
  <root>
    <level value="INFO" />
    <appender-ref ref="ConsoleAppender" />
  </root>

  <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>

2. 程式入口啟用（`Program.cs`）

[assembly: log4net.Config.XmlConfigurator(ConfigFile = "log4net.config", Watch = true)]

class Program {
    private static readonly ILog Log = LogManager.GetLogger(typeof(Program));

    static void Main() {
        Log.Info("應用啟動");
        Log.Debug("此行僅在 DEBUG 級別可見");
        Log.Error("模擬錯誤", new InvalidOperationException("測試異常"));
    }
}

3. 輸出效果

2024-01-15 14:30:45,123 [1] INFO  Program - 應用啟動
2024-01-15 14:30:45,125 [1] ERROR Program - 模擬錯誤
System.InvalidOperationException: 測試異常
   at Program.Main() in ...

進階：Logger 獲取策略

// 1. 類級別靜態字段（標準、推薦）
private static readonly ILog Log = LogManager.GetLogger(typeof(MyClass));

// 2. 字串名稱（動態、跨類共享）
var log = LogManager.GetLogger("MyApp.Audit");

// 3. 反射獲取調用類型（通用封裝基類用）
var log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

常見誤區

下一步學習路徑

1. 閱讀 《log4net 進階配置詳解（二）》：Layout 模式、Filter、RollingFileAppender、熱更新、AsyncAppender。
2. 實戰：在 ASP.NET Core 中整合 log4net（替換預設 `ILogger`），配合 Serilog 增強結構化日誌。
3. 研究 `AdoNetAppender` 表結構設計，實現日誌入庫與 SQL 分析儀表板。