萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> ASP.NET 程式設計

log4net 配置與使用完整入門指南:從 XML 設定到程式碼整合

log4net 核心架構三要素

  • Logger:記錄器,程式碼呼叫的入口 (`log.Info("訊息")`)
  • Appender:輸出目的地 (檔案、Console、資料庫、Email、Syslog...)
  • Layout:輸出格式化 (PatternLayout, JsonLayout, XmlLayout...)

關係:Logger → (參考) Appender → (使用) Layout

步驟 1:安裝套件

// NuGet 套件管理器主控台
Install-Package log4net
// 或 .NET CLI
dotnet add package log4net

步驟 2:建立 log4net.config 獨立設定檔

建議獨立檔案而非寫在 web.config,便於 `ConfigureAndWatch` 熱重載:

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

  <log4net debug="false">
    <!-- 滾動檔案 Appender:依日期+大小分割 -->
    <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
      <file value="Logs/" />
      <appendToFile value="true" />
      <rollingStyle value="Composite" />           <!-- 複合模式:日期+大小 -->
      <datePattern value="yyyy-MM-dd '.log'" />    <!-- 每日一檔 -->
      <maxSizeRollBackups value="30" />            <!-- 保留 30 個備份 -->
      <maximumFileSize value="10MB" />             <!-- 單檔上限 10MB -->
      <staticLogFileName value="true" />           <!-- 固定檔名,備份加後綴 -->
      <lockingModel type="log4net.Appender.FileAppender+MinimalLock" />
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger - %message%newline" />
      </layout>
    </appender>

    <!-- Console 輸出 (開發除錯用) -->
    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
      <layout type="log4net.Layout.PatternLayout">
        <conversionPattern value="%date [%thread] %-5level %logger - %message%newline" />
      </layout>
    </appender>

    <!-- 根 Logger 設定 -->
    <root>
      <level value="DEBUG" />                      <!-- 最低記錄等級 -->
      <appender-ref ref="RollingFileAppender" />
      <appender-ref ref="ConsoleAppender" />
    </root>

    <!-- 特定命名空間覆寫等級 (可選) -->
    <logger name="MyApp.DataAccess">
      <level value="INFO" />
    </logger>
  </log4net>
</configuration>

步驟 3:應用程式啟動時初始化

ASP.NET WebForms / MVC (Global.asax.cs)

protected void Application_Start(object sender, EventArgs e)
{
    // ConfigureAndWatch:檔案變更自動重新載入設定
    var configFile = new FileInfo(Server.MapPath("~/log4net.config"));
    log4net.Config.XmlConfigurator.ConfigureAndWatch(configFile);
}

ASP.NET Core (Program.cs / Startup.cs)

// Program.cs (.NET 6+)
var builder = WebApplication.CreateBuilder(args);

// 註冊 log4net
builder.Logging.ClearProviders();
builder.Logging.AddLog4Net("log4net.config"); // 需 Microsoft.Extensions.Logging.Log4Net.AspNetCore

var app = builder.Build();
// ...

Console / Windows Service / WPF

static void Main()
{
    var repo = LogManager.CreateRepository("MyApp");
    XmlConfigurator.Configure(repo, new FileInfo("log4net.config"));
    
    var log = LogManager.GetLogger(repo.Name, "Program");
    log.Info("應用程式啟動");
}

步驟 4:程式碼中使用 Logger

靜態欄位模式 (效能最佳)

public class OrderService
{
    // 命名慣例:類別全名 作為 logger name,方便設定檔針對性配置
    private static readonly ILog log = LogManager.GetLogger(typeof(OrderService));

    public void CreateOrder(Order order)
    {
        log.Debug($"開始建立訂單: {order.Id}");
        
        try 
        {
            // 業務邏輯...
            log.Info($"訂單建立成功: {order.Id}, 金額: {order.Total}");
        }
        catch (Exception ex)
        {
            // Error 等級會自動包含堆疊追蹤
            log.Error($"訂單建立失敗: {order.Id}", ex);
            throw;
        }
    }
}

進階:結構化日誌 (搭配 JsonLayout)

<appender name="JsonFileAppender" type="log4net.Appender.RollingFileAppender">
  <file value="Logs/json/" />
  <datePattern value="yyyy-MM-dd '.json'" />
  <rollingStyle value="Date" />
  <layout type="log4net.Layout.SerializedLayout, log4net.Ext.Json">
    <decorator type="log4net.Layout.Decorators.StandardTypesDecorator, log4net.Ext.Json" />
    <member value="timestamp:date" />
    <member value="level:level" />
    <member value="logger:logger" />
    <member value="message:message" />
    <member value="exception:exception" />
    <member value="properties:properties" />
  </layout>
</appender>

需安裝 `log4net.Ext.Json` NuGet 套件。輸出標準 JSON,直接支援 ELK、Splunk 等日誌分析平台。

常用 PatternLayout 佔位符對照表

符號含義範例輸出
%date日期時間2024-01-15 14:30:45,123
%date{yyyy-MM-dd HH:mm:ss}自訂日期格式2024-01-15 14:30:45
%thread執行緒名稱/ID12 或 MainThread
%-5level等級 (左靠 5 字寬)DEBUG, INFO , WARN , ERROR
%loggerLogger 名稱 (類別全名)MyApp.Services.OrderService
%message / %m日誌訊息訂單建立成功
%exception / %e例外堆疊追蹤System.NullReferenceException...
%property{key}ThreadContext/LogicalThreadContext 屬性UserId=123
%newline / %n換行(換行)

日誌等級說明 (由高到低)

  1. OFF:關閉所有記錄
  2. FATAL:嚴重錯誤,導致應用程式終止
  3. ERROR:錯誤事件,但應用程式可繼續執行
  4. WARN:潛在問題,非立即錯誤
  5. INFO:一般資訊,關鍵業務節點
  6. DEBUG:除錯詳細資訊
  7. ALL:記錄所有等級

設定 `` 會記錄 INFO、WARN、ERROR、FATAL,不記錄 DEBUG。

最佳實踐清單

  1. 靜態 readonly Logger:避免重複建立,效能最佳
  2. 使用 `typeof(ThisClass)` 命名:利於設定檔依命名空間篩選
  3. 判斷等級再建構字串:`if (log.IsDebugEnabled) log.Debug($"複雜物件: {JsonConvert.SerializeObject(obj)}");` 避免不必要序列化開銷
  4. 例外傳入獨立參數:`log.Error("訊息", ex)` 而非 `log.Error("訊息: " + ex)`,保留完整堆疊
  5. 生產環境設定 INFO/WARN 以上:DEBUG 量大影響效能與磁碟
  6. 配置 MinimalLock:多進程/多執行緒寫入同一檔案不衝突
  7. 定期備份/清理策略:搭配 `maxSizeRollBackups` 與外部排程清理

總結

log4net 透過 XML 設定檔分離配置與程式碼,支援熱重載、多 Appender、彈性格式化。掌握「Logger-Appender-Layout」三要素關係、正確初始化時機、靜態 Logger 模式與等級控制,即可建立生產級日誌系統。現代專案可考慮 Serilog (結構化優先) 或 Microsoft.Extensions.Logging 統一抽象,但 log4net 仍是 .NET Framework 專案最成熟穩定的選擇。

copyright © 萬盛學電腦網 all rights reserved