ErrorMessageException Samples

異常 log 範例

⚠️ v3.0 起,ErrorMessageException 不再是公開 API(原 v2.x 提供的測試輔助類別已移至 OzaLog.Test 專案內)。本頁示範如何用標準 Exception 或自訂 Exception 子類別做異常 log。

---

直接 log 標準 .NET 異常

using OzaLog;

try
{
    int.Parse("not a number");
}
catch (FormatException ex)
{
    LOG.Error_Log(ex);
}

→ OzaLog 自動把異常結構化為 JSON,包含:

• Type / Message / Source / HelpLink / StackTrace
• Data(從 ex.Data 字典展開)
• InnerException(遞迴展開所有內層)
• AdditionalProperties(反射撈出非標準屬性,例如自訂 Exception 類別的 public property)

---

加上上下文訊息

try
{
    PlaceOrder(symbol, price);
}
catch (Exception ex)
{
    LOG.Error_Log($"PlaceOrder({symbol}, {price}) 失敗", ex);
}

---

自訂異常類別

public class TradeFailedException : Exception
{
    public string Symbol { get; }
    public decimal Price { get; }

    public TradeFailedException(string symbol, decimal price, string message)
        : base(message)
    {
        Symbol = symbol;
        Price = price;
    }
}

// 使用:
try
{
    throw new TradeFailedException("BTC", 67890.12m, "下單失敗");
}
catch (TradeFailedException ex)
{
    LOG.Error_Log(ex);
}

→ JSON 輸出會自動包含 Symbol 與 Price 屬性(透過 AdditionalProperties)。

---

自動 flush

Error_Log 與 Fatal_Log 預設就會立即 flush 到磁碟,確保異常 log 在程式 crash 前就落盤。

LOG.Error_Log(ex);   // ← 自動立即 flush,不等異步隊列批次
LOG.Fatal_Log(ex);   // ← 同上

---

全域意外攔截(v3.0 新功能,opt-in)

不想每個 try/catch 都手動寫 LOG.Error_Log?啟用全域攔截:

LOG.Configure(o =>
{
    o.EnableGlobalExceptionCapture = true;
});

啟用後會自動訂閱:

• AppDomain.CurrentDomain.UnhandledException
• TaskScheduler.UnobservedTaskException

未捕獲的異常會以 Fatal 級別、同步立即 flush 寫入 Fatal_Log.txt,確保 crash log 落盤。

⚠️ 限制: 此功能不會攔截:

• WPF / WinForms UI 執行緒例外(需自行 hook Application.DispatcherUnhandledException)
• ASP.NET Core middleware 例外(需走 ExceptionHandler middleware)
• 已被 try/catch 接住的例外(本就不會冒到 AppDomain)

---

v2.x 升級對照

v2.x 寫法	v3.0 等價寫法
using ozakboy.NLOG;	using OzaLog;
throw new ErrorMessageException("..."); LOG.Warn_Log(ex);	改用標準 throw new Exception("..."); 或自訂 Exception 類別,搭配 LOG.Warn_Log(ex)

完整升級指南: docs/zh-TW/migration.md