Implementieren eines benutzerdefinierten Protokollierungsanbieters in .NET

Viele Protokollierungsanbieter sind für allgemeine Protokollierungsanforderungen verfügbar. Möglicherweise müssen Sie jedoch einen benutzerdefinierten ILoggerProvider Implementieren, wenn einer der verfügbaren Anbieter nicht ihren Anwendungsanforderungen entspricht. In diesem Artikel erfahren Sie, wie Sie einen benutzerdefinierten Protokollierungsanbieter implementieren, der zum Einfärben von Protokollen in der Konsole verwendet werden kann.

Tipp

Der beispielcode für den benutzerdefinierten Protokollierungsanbieter ist im GitHub-Repository für Dokumente verfügbar.

Beispiel für eine benutzerdefinierte Loggerkonfiguration

Der Beispielprotokollierer erstellt verschiedene Farbkonsoleneinträge pro Protokollebene und Ereignis-ID mit dem folgenden Konfigurationstyp:

using Microsoft.Extensions.Logging;

public sealed class ColorConsoleLoggerConfiguration
{
    public int EventId { get; set; }

    public Dictionary<LogLevel, ConsoleColor> LogLevelToColorMap { get; set; } = new()
    {
        [LogLevel.Information] = ConsoleColor.Green
    };
}

Der vorangehende Code legt die Standardfarbe für die Information Ebene auf Green. Dies EventId ist implizit 0.

Erstellen des benutzerdefinierten Loggers

Der folgende Codeausschnitt zeigt die ILogger Implementierung:

using Microsoft.Extensions.Logging;

public sealed class ColorConsoleLogger(
    string name,
    Func<ColorConsoleLoggerConfiguration> getCurrentConfig) : ILogger
{
    public IDisposable? BeginScope<TState>(TState state)
        where TState : notnull => default!;

    public bool IsEnabled(LogLevel logLevel) =>
        getCurrentConfig().LogLevelToColorMap.ContainsKey(logLevel);

    public void Log<TState>(
        LogLevel logLevel,
        EventId eventId,
        TState state,
        Exception? exception,
        Func<TState, Exception?, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        ColorConsoleLoggerConfiguration config = getCurrentConfig();
        if (config.EventId == 0 || config.EventId == eventId.Id)
        {
            ConsoleColor originalColor = Console.ForegroundColor;

            Console.ForegroundColor = config.LogLevelToColorMap[logLevel];
            Console.WriteLine($"[{eventId.Id,2}: {logLevel,-12}]");
            
            Console.ForegroundColor = originalColor;
            Console.Write($"     {name} - ");

            Console.ForegroundColor = config.LogLevelToColorMap[logLevel];
            Console.Write($"{formatter(state, exception)}");
            
            Console.ForegroundColor = originalColor;
            Console.WriteLine();
        }
    }
}

Jede Loggerinstanz wird instanziiert, indem ein Kategoriename übergeben wird. Dies ist in der Regel der Typ, in dem der Logger erstellt wird. Die IsEnabled Methode überprüft getCurrentConfig().LogLevelToColorMap.ContainsKey(logLevel) , ob die angeforderte Protokollebene aktiviert ist (d. h. im Verzeichnis der Protokollebenen der Konfiguration).

Es empfiehlt sich, ILogger.IsEnabled innerhalb der ILogger.Log-Implementierungen aufzurufen, da Log von jedem Nutzer aufgerufen werden kann, und es gibt keine Garantien, dass er zuvor überprüft wurde. Die IsEnabled Methode sollte in den meisten Implementierungen sehr schnell sein.

if (!IsEnabled(logLevel))
{
    return;
}

Der Logger wird mit name und Func<ColorConsoleLoggerConfiguration> instanziiert, die den aktuellen Konfigurationsstand zurückgeben.

Von Bedeutung

Die ILogger.Log Implementierung überprüft, ob der config.EventId Wert festgelegt ist. Wenn config.EventId nicht festgelegt ist oder mit dem genauen logEntry.EventIdübereinstimmt, gibt der Logger die Protokolle in Farbe aus.

Benutzerdefinierter Loggeranbieter

Das ILoggerProvider-Objekt ist für das Erstellen von Loggerinstanzen verantwortlich. Es ist nicht erforderlich, eine Loggerinstanz pro Kategorie zu erstellen, aber es ist sinnvoll für einige Logger, z. B. NLog oder Log4net. Mit dieser Strategie können Sie unterschiedliche Protokollierungsausgabeziele pro Kategorie auswählen, wie im folgenden Beispiel gezeigt:

using System.Collections.Concurrent;
using System.Runtime.Versioning;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

[UnsupportedOSPlatform("browser")]
[ProviderAlias("ColorConsole")]
public sealed class ColorConsoleLoggerProvider : ILoggerProvider
{
    private readonly IDisposable? _onChangeToken;
    private ColorConsoleLoggerConfiguration _currentConfig;
    private readonly ConcurrentDictionary<string, ColorConsoleLogger> _loggers =
        new(StringComparer.OrdinalIgnoreCase);

    public ColorConsoleLoggerProvider(
        IOptionsMonitor<ColorConsoleLoggerConfiguration> config)
    {
        _currentConfig = config.CurrentValue;
        _onChangeToken = config.OnChange(updatedConfig => _currentConfig = updatedConfig);
    }

    public ILogger CreateLogger(string categoryName) =>
        _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, GetCurrentConfig));

    private ColorConsoleLoggerConfiguration GetCurrentConfig() => _currentConfig;

    public void Dispose()
    {
        _loggers.Clear();
        _onChangeToken?.Dispose();
    }
}

Im vorherigen Code erstellt CreateLogger(String) eine einzelne Instanz des ColorConsoleLogger pro Kategorienamen und speichert sie im ConcurrentDictionary<TKey,TValue>.

Die ColorConsoleLoggerProvider Klasse ist mit zwei Attributen versehen:

[UnsupportedOSPlatform("browser")]
[ProviderAlias("ColorConsole")]
public sealed class ColorConsoleLoggerProvider : ILoggerProvider

• UnsupportedOSPlatformAttribute: Für den Typ ColorConsoleLogger gibt es keine Unterstützung in "browser".
• ProviderAliasAttribute: Konfigurationsabschnitte können Optionen mithilfe des "ColorConsole" Schlüssels definieren.

Die Konfiguration kann mit jedem gültigen Konfigurationsanbieterfestgelegt werden. Sehen Sie sich die nachfolgende Datei appsettings.json an:

{
    "Logging": {
        "ColorConsole": {
            "LogLevelToColorMap": {
                "Information": "DarkGreen",
                "Warning": "Cyan",
                "Error": "Red"
            }
        }
    }
}

Die appsettings.json-Datei gibt an, dass die Farbe der Information Protokollebene auf DarkGreen festgelegt ist, wodurch der Standardwert, der im ColorConsoleLoggerConfiguration-Objekt festgelegt wurde, überschrieben wird.

Nutzung und Registrierung des benutzerdefinierten Loggers

Standardmäßig werden Dienste als Teil der Startroutine einer Anwendung für die Abhängigkeitsinjektion registriert. In diesem Beispiel wird der Protokollierungsdienst direkt aus der Program.cs-Datei registriert.

Um den benutzerdefinierten Protokollierungsanbieter und den entsprechenden Logger hinzuzufügen, fügen Sie eine ILoggerProvider hinzu, indem Sie eine benutzerdefinierte Erweiterungsmethode AddColorConsoleLogger für den ILoggingBuilder aus der IHostApplicationBuilder.Logging Eigenschaft aufrufen.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddColorConsoleLogger(configuration =>
{
    // Replace value of "Cyan" from appsettings.json.
    configuration.LogLevelToColorMap[LogLevel.Warning]
        = ConsoleColor.DarkCyan;
    // Replace value of "Red" from appsettings.json.
    configuration.LogLevelToColorMap[LogLevel.Error]
        = ConsoleColor.DarkRed;
});

using IHost host = builder.Build();

ILogger<Program> logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogDebug(1, "Does this line get hit?");    // Not logged
logger.LogInformation(3, "Nothing to see here."); // Logs in ConsoleColor.DarkGreen
logger.LogWarning(5, "Warning... that was odd."); // Logs in ConsoleColor.DarkCyan
logger.LogError(7, "Oops, there was an error.");  // Logs in ConsoleColor.DarkRed
logger.LogTrace(5, "== 120.");                    // Not logged

await host.RunAsync();

Standardmäßig werden Erweiterungsmethoden für ILoggingBuilder verwendet, um den benutzerdefinierten Anbieter zu registrieren:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Configuration;

public static class ColorConsoleLoggerExtensions
{
    public static ILoggingBuilder AddColorConsoleLogger(
        this ILoggingBuilder builder)
    {
        builder.AddConfiguration();

        builder.Services.TryAddEnumerable(
            ServiceDescriptor.Singleton<ILoggerProvider, ColorConsoleLoggerProvider>());

        LoggerProviderOptions.RegisterProviderOptions
            <ColorConsoleLoggerConfiguration, ColorConsoleLoggerProvider>(builder.Services);

        return builder;
    }

    public static ILoggingBuilder AddColorConsoleLogger(
        this ILoggingBuilder builder,
        Action<ColorConsoleLoggerConfiguration> configure)
    {
        builder.AddColorConsoleLogger();
        builder.Services.Configure(configure);

        return builder;
    }
}

ILoggingBuilder erstellt mindestens eine ILogger-Instanz. Die ILogger Instanzen werden vom Framework verwendet, um die Informationen zu protokollieren.

Der Instanziierungscode überschreibt die Farbwerte aus der appsettings.json Datei für LogLevel.Warning und LogLevel.Error.

Wenn Sie diese einfache App ausführen, wird die Farbausgabe im Konsolenfenster ähnlich wie in der folgenden Abbildung gerendert:

Siehe auch

• Protokollierung in .NET
• Protokollierungsanbieter in .NET
• Abhängigkeitsinjektion in .NET
• Hochleistungsprotokollierung in .NET