@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/18-/346/227/245/350/252/214/350/250/230/351/214/204.md

@@ -0,0 +1,639 @@
+# 18. 日誌記錄
+
+## 18.1 關於日誌
+
+- **系統日誌**：記錄系統中硬體、軟體和系統問題的資訊，可監視系統中發生的事件
+- **程式日誌**：程式執行中產生的日誌，包括請求日誌、例外日誌、稽核日誌、行為日誌等
+
+## 18.2 日誌作用
+
+- **偵錯**：查看堆疊資訊方便知道當前程式的執行狀態
+- **錯誤定位**：快速定位錯誤位置，提出解決方案
+- **資料分析**：日誌中蘊含大量的使用者資料，對公司策略有指引作用
+
+## 18.3 日誌級別
+
+| 級別 | 值 | 方法 | 描述 |
+|------|---|------|------|
+| Trace | 0 | `LogTrace` | 最詳細的訊息，預設停用 |
+| Debug | 1 | `LogDebug` | 用於偵錯和開發 |
+| Information | 2 | `LogInformation` | 追蹤應用的常規流 |
+| Warning | 3 | `LogWarning` | 異常事件或意外事件 |
+| Error | 4 | `LogError` | 無法處理的錯誤和例外 |
+| Critical | 5 | `LogCritical` | 需要立即關注的失敗 |
+
+---
+
+## 18.4 如何使用
+
+### 18.4.1 ILogger\<T\> 泛型方式
+
+```csharp
+public class PrivacyModel : PageModel
+{
+    private readonly ILogger<PrivacyModel> _logger;
+
+    public PrivacyModel(ILogger<PrivacyModel> logger)
+    {
+        _logger = logger;
+    }
+
+    public void OnGet()
+    {
+        _logger.LogInformation("GET Pages.PrivacyModel called.");
+    }
+}
+```
+
+### 18.4.2 ILoggerFactory 工廠方式
+
+```csharp
+public class ContactModel : PageModel
+{
+    private readonly ILogger _logger;
+
+    public ContactModel(ILoggerFactory logger)
+    {
+        _logger = logger.CreateLogger("MyCategory");
+    }
+}
+```
+
+### 18.4.3 Log 靜態類別方式（Furion 4.2.1+）
+
+```csharp
+var logger = Log.CreateLogger("日誌名稱");
+
+Log.Information("Information");
+Log.Warning("Warning");
+Log.Error("Error");
+Log.Debug("Debug");
+Log.Trace("Trace");
+Log.Critical("Critical");
+```
+
+### 18.4.4 懶人模式 😁
+
+```csharp
+"簡單日誌".LogInformation();
+"百小僧 新增了一條記錄".LogInformation<HomeController>();
+"程式出現例外啦".LogError<HomeController>();
+"這是自訂類別日誌".SetCategory<HomeController>().LogInformation();
+```
+
+---
+
+## 18.5 輸出到主控台
+
+### 18.5.1 日誌過濾/篩選
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.WriteFilter = (logMsg) =>
+    {
+        return logMsg.LogLevel == LogLevel.Information;
+    };
+});
+```
+
+### 18.5.2 日誌標準化（美化）範本（Furion 4.5.0+）
+
+```csharp
+services.AddConsoleFormatter();
+// 或在 .NET6 中：builder.Logging.AddConsoleFormatter();
+```
+
+### 18.5.3 自訂日誌範本
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.MessageFormat = (logMsg) =>
+    {
+        var sb = new StringBuilder();
+        sb.Append(DateTime.Now.ToString("o"));
+        return sb.ToString();
+    };
+});
+
+// 輸出為 JSON 格式（Furion 4.5.2+）
+services.AddConsoleFormatter(options =>
+{
+    options.MessageFormat = LoggerFormatter.Json;
+    // Furion 4.8.0+ 新增 JSON 美化輸出
+    options.MessageFormat = LoggerFormatter.JsonIndented;
+});
+```
+
+### 18.5.4 自訂日誌輸出時間格式（Furion 4.5.1+）
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.DateFormat = "yyyy-MM-dd HH:mm:ss.fffffff zzz dddd";
+});
+```
+
+### 18.5.5 自訂日誌輸出程式（Furion 4.5.2+）
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.WriteHandler = (logMsg, scopeProvider, writer, fmtMsg, opt) =>
+    {
+        writer.WriteLine(fmtMsg);
+    };
+});
+```
+
+### 18.5.6 輸出日誌 TraceId（Furion 4.8.1.3+）
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.WithTraceId = true;
+});
+```
+
+### 18.5.7 輸出日誌程式集/型別/方法（Furion 4.8.7.16+）
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.WithStackFrame = true;
+});
+```
+
+### 18.5.8 日誌訊息額外處理（Furion 4.9.2.32+）
+
+```csharp
+services.AddConsoleFormatter(options =>
+{
+    options.MessageProcess = (originalMessage) =>
+    {
+        return 脫敏處理(originalMessage);
+    };
+});
+```
+
+---
+
+## 18.6 輸出到檔案
+
+### 18.6.1 基礎使用
+
+```csharp
+services.AddFileLogging("application.log");
+services.AddFileLogging("logs/application.log");
+services.AddFileLogging("application.log", true); // true 為追加，false 為覆蓋
+```
+
+### 18.6.2 從設定檔讀取設定
+
+> ⚠️ 只有不在 `.AddFile` 第一個參數設定檔案名稱才會自動載入設定。
+
+```json
+{
+  "Logging": {
+    "File": {
+      "FileName": "application.log",
+      "Append": true,
+      "MinimumLevel": "Information",
+      "FileSizeLimitBytes": 0,
+      "MaxRollingFiles": 0
+    }
+  }
+}
+```
+
+```csharp
+services.AddFileLogging(); // 預設讀取 Logging:File 節點
+
+services.AddFileLogging(() => "MyLogger"); // 自訂設定節點
+
+services.AddFileLogging(options =>
+{
+    options.MinimumLevel = LogLevel.Warning;
+});
+```
+
+### 18.6.3 自訂日誌檔案名稱規則
+
+```csharp
+// 每天建立一個日誌檔案
+services.AddFileLogging("application-{0:yyyy}-{0:MM}-{0:dd}.log", options =>
+{
+    options.FileNameRule = fileName => string.Format(fileName, DateTime.UtcNow);
+});
+
+// 批次設定多個（依級別分檔）
+Array.ForEach(new[] { LogLevel.Information, LogLevel.Warning, LogLevel.Error }, logLevel =>
+{
+    services.AddFileLogging("application-{1}-{0:yyyy}-{0:MM}-{0:dd}.log", options =>
+    {
+        options.FileNameRule = fileName => string.Format(fileName, DateTime.UtcNow, logLevel.ToString());
+        options.WriteFilter = logMsg => logMsg.LogLevel == logLevel;
+    });
+});
+```
+
+### 18.6.4 日誌過濾器/篩選器
+
+```csharp
+services.AddFileLogging("information.log", options =>
+{
+    options.WriteFilter = (logMsg) => logMsg.LogLevel == LogLevel.Information;
+});
+
+services.AddFileLogging("error.log", options =>
+{
+    options.WriteFilter = (logMsg) => logMsg.LogLevel == LogLevel.Error;
+});
+```
+
+### 18.6.5 自訂日誌範本
+
+```csharp
+services.AddFileLogging("mytemplate.log", options =>
+{
+    options.MessageFormat = (logMsg) =>
+    {
+        var sb = new StringBuilder();
+        sb.Append(DateTime.Now.ToString("o"));
+        return sb.ToString();
+    };
+});
+
+// JSON 格式（Furion 4.5.2+）
+services.AddFileLogging("mytemplate.log", options =>
+{
+    options.MessageFormat = LoggerFormatter.Json;
+});
+```
+
+### 18.6.6 日誌寫入失敗處理
+
+```csharp
+services.AddFileLogging("template-obj.log", options =>
+{
+    options.HandleWriteError = (writeError) =>
+    {
+        // 啟用備用日誌檔案（推薦）
+        writeError.UseRollbackFileName(
+            Path.GetFileNameWithoutExtension(writeError.CurrentFileName)
+            + "-oops" + Path.GetExtension(writeError.CurrentFileName));
+    };
+});
+```
+
+---
+
+## 18.7 輸出到資料庫/其他儲存媒體
+
+### 建立資料庫日誌寫入器
+
+```csharp
+using Furion.Logging;
+
+namespace YourProject.Core;
+
+public class DatabaseLoggingWriter : IDatabaseLoggingWriter
+{
+    public DatabaseLoggingWriter() { } // 支援建構函式注入
+
+    public Task WriteAsync(LogMessage logMsg, bool flush)
+    {
+        // 這裡寫你任何插入資料庫的操作，無需 try catch
+    }
+}
+```
+
+> ⚠️ 在 Furion 4.8.5.4+ 版本之後，如果注入了 `ILogger<>` 實例，將強制實例化為 `EmptyLogger` 物件，避免死迴圈。
+
+### 18.7.1 基礎使用
+
+```csharp
+services.AddDatabaseLogging<DatabaseLoggingWriter>(options => {});
+
+services.AddDatabaseLogging<DatabaseLoggingWriter>(options =>
+{
+    options.MinimumLevel = LogLevel.Warning;
+});
+```
+
+### 18.7.2 從設定檔中讀取
+
+```json
+{
+  "Logging": {
+    "Database": {
+      "MinimumLevel": "Information"
+    }
+  }
+}
+```
+
+```csharp
+services.AddDatabaseLogging<DatabaseLoggingWriter>(); // 預設讀取 Logging:Database
+services.AddDatabaseLogging<DatabaseLoggingWriter>("MyLogger"); // 自訂設定節點
+```
+
+### 18.7.3~18.7.7 進階設定
+
+日誌過濾、自訂範本、寫入失敗處理、TraceId、WithStackFrame 等設定方式與檔案日誌相同，將 `AddFileLogging` 替換為 `AddDatabaseLogging<T>` 即可。
+
+### 18.7.8 關於高頻寫入儲存媒體
+
+```csharp
+public class DatabaseLoggingWriter : IDatabaseLoggingWriter, IDisposable
+{
+    private readonly IServiceScope _serviceScope;
+    private readonly IRepository<LogTable> _logRepository;
+
+    public DatabaseLoggingWriter(IServiceScopeFactory scopeFactory)
+    {
+        _serviceScope = scopeFactory.CreateScope();
+        _logRepository = _serviceScope.ServiceProvider.GetRequiredService<IRepository<LogTable>>();
+    }
+
+    public Task WriteAsync(LogMessage logMsg, bool flush)
+    {
+        _logRepository.Insert(/* ... */);
+    }
+
+    public void Dispose() => _serviceScope.Dispose();
+}
+```
+
+### 18.7.9 關於資料庫日誌循環輸出
+
+ORM 本身操作資料庫時自帶日誌輸出會導致 `IDatabaseLoggingWriter` 的 `Write` 死迴圈。解決方式：建立新的資料庫操作實例並關閉日誌，或更新到 Furion 4.7.0+。如不存在該問題可關閉偵測：
+
+```csharp
+services.AddDatabaseLogging<DatabaseLoggingWriter>(options =>
+{
+    options.IgnoreReferenceLoop = false;
+});
+```
+
+---
+
+## 18.8 新增日誌提供器方式
+
+```csharp
+// ILoggingBuilder 方式
+services.AddLogging(builder =>
+{
+    builder.AddFile("application.log");
+    builder.AddDatabase<DatabaseLoggingWriter>();
+});
+
+// LoggerFactory 方式（執行時動態新增，需自行釋放）
+var loggerFactory = LoggerFactory.Create(builder => builder.AddFile("application.log"));
+var logger = loggerFactory.CreateLogger("MyCategory");
+```
+
+---
+
+## 18.10 Debug 與 Trace 日誌預設不輸出問題
+
+預設 `LogLevel.Default` 為 `Information`，低於此級別的 Debug 和 Trace 不會輸出。在 `appsettings.json` 中修改：
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Trace",
+      "System.Logging.StringLogging": "Trace"
+    }
+  }
+}
+```
+
+---
+
+## 18.11 [LoggingMonitor] 監聽日誌
+
+> ⚠️ **生產環境**應關閉 LoggingMonitor 功能，全域啟用對效能有一定影響。
+
+### 18.11.1 特性設定
+
+```csharp
+[LoggingMonitor]
+public PersonDto GetPerson(int id) => new PersonDto { Id = id };
+```
+
+`[LoggingMonitor]` 支援設定：`Title`、`WithReturnValue`、`ReturnValueThreshold`、`JsonBehavior`、`JsonIndented`、`LongTypeConverter`。
+
+### 18.11.2 全域設定
+
+```csharp
+services.AddMonitorLogging(); // 預設讀取 Logging:Monitor 下設定
+```
+
+```json
+{
+  "Logging": {
+    "Monitor": {
+      "GlobalEnabled": false,
+      "IncludeOfMethods": [],
+      "ExcludeOfMethods": [],
+      "LogLevel": "Information",
+      "BahLogLevel": "Information",
+      "WithReturnValue": true,
+      "ReturnValueThreshold": 0,
+      "JsonBehavior": "None",
+      "JsonIndented": false,
+      "LongTypeConverter": false,
+      "ContractResolver": "CamelCase",
+      "MethodsSettings": [
+        {
+          "FullName": "Furion.Application.TestLoggerServices.MethodName",
+          "WithReturnValue": true,
+          "ReturnValueThreshold": 0,
+          "JsonBehavior": "None",
+          "JsonIndented": false,
+          "ContractResolver": "CamelCase"
+        }
+      ]
+    }
+  }
+}
+```
+
+> `IncludeOfMethods` 和 `ExcludeOfMethods` 格式為：`類完全限定名.方法名`。個別不需要監視的介面貼 `[SuppressMonitor]` 特性即可。
+
+### 18.11.3 更多設定（Furion 4.3.9+）
+
+```csharp
+services.AddMonitorLogging(options =>
+{
+    options.ConfigureLogger((logger, logContext, context) =>
+    {
+        var httpContext = context.HttpContext;
+        logContext.Set("extra", "其他資料");
+    });
+});
+```
+
+### 18.11.4 JSON 格式（Furion 4.5.2+）
+
+```csharp
+// 全域
+services.AddMonitorLogging(options =>
+{
+    options.JsonBehavior = JsonBehavior.OnlyJson;
+    options.JsonIndented = true;
+});
+
+// 局部
+[LoggingMonitor(JsonBehavior = JsonBehavior.OnlyJson, JsonIndented = true)]
+```
+
+在 `IDatabaseLoggingWriter` 中讀取 JSON：
+
+```csharp
+public Task WriteAsync(LogMessage logMsg, bool flush)
+{
+    if (logMsg.LogName == "System.Logging.LoggingMonitor")
+    {
+        var jsonString = logMsg.Context.Get("loggingMonitor");
+    }
+}
+```
+
+### 18.11.5 全域過濾 WriteFilter（Furion 4.5.9+）
+
+```csharp
+services.AddMonitorLogging(options =>
+{
+    options.WriteFilter = (context) =>
+    {
+        var descriptor = context.ActionDescriptor as ControllerActionDescriptor;
+        return true; // 需要攔截回傳 false
+    };
+});
+```
+
+### 18.11.6 忽略屬性名或屬性型別（Furion 4.6.1+）
+
+```csharp
+// 局部
+[LoggingMonitor(JsonBehavior = JsonBehavior.OnlyJson,
+    IgnorePropertyNames = new[] { "Bytes" },
+    IgnorePropertyTypes = new[] { typeof(byte[]) })]
+
+// 全域
+services.AddMonitorLogging(options =>
+{
+    options.IgnorePropertyNames = new[] { "Byte" };
+    options.IgnorePropertyTypes = new[] { typeof(byte[]) };
+});
+```
+
+### 18.11.7 將 LoggingMonitor 寫入資料庫
+
+```csharp
+services.AddDatabaseLogging<DatabaseLoggingWriter>(options =>
+{
+    options.WriteFilter = (logMsg) => logMsg.LogName == "System.Logging.LoggingMonitor";
+});
+```
+
+### 18.11.10 跳過特定參數記錄（Furion 4.8.7.3+）
+
+```csharp
+[LoggingMonitor]
+public string GetName([SuppressMonitor] SomeType type, int id) => nameof(Furion);
+```
+
+### 18.11.11 設定稽核日誌附加資訊（Furion 4.9.4.6+）
+
+```csharp
+[LoggingMonitor]
+public void AddUser()
+{
+    LoggingMonitorContext.Append((items, httpContext) =>
+    {
+        items.Add("框架作者", "百小僧");
+        items.Add("User-Agent", httpContext.Request.Headers.UserAgent);
+    });
+}
+```
+
+### 18.11.13 過濾特定條目輸出（Furion 4.9.7.127+）
+
+```csharp
+services.AddMonitorLogging(options =>
+{
+    options.ItemFilter = key => key != "Authorization";
+});
+```
+
+---
+
+## 18.15 日誌上下文（Furion 4.6.0+）
+
+### 18.15.1 新增上下文資料
+
+```csharp
+// 寫法一
+using (var scope = _logger.ScopeContext(ctx => ctx.Set("Name", "Furion").Set("UserId", 10)))
+{
+    _logger.LogInformation("我是一個日誌 {id}", 20);
+}
+
+// 寫法二
+using var scope = _logger.ScopeContext(new Dictionary<object, object> {
+    { "Name", "Furion" }, { "UserId", 10 }
+});
+
+// 多次設定上下文（Furion 4.9.8.18+）
+using var scope = _logger.CreateScope();
+scope.WithContext(ctx => ctx.Set("Name", "Furion"));
+_logger.LogInformation("日誌一");
+scope.WithContext(ctx => ctx.Set("Other", "Some"));
+_logger.LogInformation("日誌二");
+```
+
+### 18.15.2 讀取上下文資料
+
+```csharp
+var value = logMsg.Context.Get("Key");
+var scopes = logMsg.Context.Scopes; // Furion 4.9.3+ 支援
+```
+
+---
+
+## 18.16 關閉 .NET Core 底層日誌
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Microsoft.EntityFrameworkCore": "Information",
+      "System.Net.Http.HttpClient": "Warning"
+    }
+  }
+}
+```
+
+---
+
+## 18.17 全域日誌過濾/篩選
+
+> ⚠️ 此方式會影響所有的日誌介質輸出（主控台、檔案、資料庫等）。
+
+```csharp
+// .NET6+
+builder.Logging.AddFilter((provider, category, logLevel) =>
+{
+    return !new[] { "Microsoft.Hosting", "Microsoft.AspNetCore" }.Any(u => category.StartsWith(u))
+        && logLevel >= LogLevel.Information;
+});
+```
+
+> **日誌過濾無效情況**：請確認 `appsettings.json` 中沒有配置 `"Microsoft": "Warning"` 和 `"Microsoft.Hosting.Lifetime": "Information"`，如果有請刪除。