LoggerMessageAttribute 高效能的日誌記錄

chester·chen發表於2024-03-15

.NET 6 引入了 LoggerMessageAttribute 型別。 使用時，它會以source-generators的方式生成高效能的日誌記錄 API。

source-generators可在編譯程式碼時，可以提供其他原始碼作為編譯的輸入。

LoggerMessageAttribute依賴於 ILogger 介面和 LoggerMessage.Define 功能。

在 partial 日誌記錄方法上使用 LoggerMessageAttribute 時，系統會觸發源生成器。 觸發後，它既可以自動生成其修飾的 partial 方法的實現，也可以生成包含正確用法提示的編譯時診斷。

與現有的日誌記錄方法相比，編譯時日誌記錄解決方案在執行時通常要快得多。 這是因為它最大限度地消除了裝箱、臨時分配和副本。

基本用法

使用 LoggerMessageAttribute 時，類和方法必須為 partial。 真實記錄日誌的程式碼生成器在編譯時觸發，並生成 partial 方法的實現。

public static partial class Log
{
    [LoggerMessage(
        EventId = 0,
        Level = LogLevel.Error,
        Message = "Can not open SQL connection {err}")]
    public static partial void CouldNotOpenConnection(this ILogger logger, string err);
}

在上面的示例中，日誌記錄方法為 static，日誌級別在屬性定義中指定，並使用 this 關鍵字將方法定義為擴充套件方法。

在呼叫時，可按常規方式呼叫即可

internal class Program
{
    private static async Task Main(string[] args)
    {

        using ILoggerFactory loggerFactory = LoggerFactory.Create(
            builder =>
            builder.AddJsonConsole(
                options =>
                options.JsonWriterOptions = new JsonWriterOptions()
                {
                    Indented = true
                }));

        ILogger logger = loggerFactory.CreateLogger("Program");

        logger.CouldNotOpenConnection("network err");
    }
}

使用規則

在日誌記錄方法上使用 LoggerMessageAttribute 時，必須遵循一些規則：

  • 日誌記錄方法必須為 partial 並返回 void。
  • 日誌記錄方法名稱不得以下劃線開頭。
  • 日誌記錄方法的引數名稱不得以下劃線開頭。
  • 日誌記錄方法不得在巢狀型別中定義。
  • 日誌記錄方法不能是泛型方法。
  • 如果日誌記錄方法是 static，則需要 ILogger 例項作為引數。

程式碼生成模型依賴於使用新式 C# 編譯器 9 或更高版本編譯的程式碼。 .NET 5 提供了 C# 9.0 編譯器。 若要升級到新式 C# 編譯器，請編輯專案檔案以面向 C# 9.0。

好處

使用源生成器方法有幾個主要好處：

  • 允許保留日誌記錄結構，並啟用訊息模板所需的確切格式語法。
  • 允許為模板佔位符提供替代名稱，允許使用格式說明符。
  • 允許按原樣傳遞所有原始資料，在對其進行處理之前，不需要進行任何複雜的儲存（除了建立 string）。
  • 提供特定於日誌記錄的診斷，針對重複的事件 ID 發出警告。

https://devblogs.microsoft.com/dotnet/introducing-c-source-generators/

https://learn.microsoft.com/zh-cn/dotnet/csharp/language-reference/keywords/partial-method

https://learn.microsoft.com/zh-cn/dotnet/core/extensions/logger-message-generator

相關文章