LoggerMessageAttribute 高性能的日誌記錄

.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