Veraltete Eigenschaften in ConsoleLoggerOptions

Der Typ Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat und einige Eigenschaften in ConsoleLoggerOptions sind nun veraltet.

Änderungsbeschreibung

Ab .NET 5 sind der Typ Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat und mehrere Eigenschaften in ConsoleLoggerOptions veraltet. Die veraltete Eigenschaften sind:

• ConsoleLoggerOptions.DisableColors
• ConsoleLoggerOptions.IncludeScopes
• ConsoleLoggerOptions.TimestampFormat
• ConsoleLoggerOptions.UseUtcTimestamp
• ConsoleLoggerOptions.Format

Infolge der Einführung von neuen Formatierern sind diese Eigenschaften jetzt in den einzelnen Formatierern verfügbar.

Grund für die Änderung

Die Eigenschaft Format ist ein Enumerationstyp, der keinen benutzerdefinierten Formatierer darstellen kann.

Die übrigen Eigenschaften wurden in ConsoleLoggerOptions festgelegt und auf beide integrierten Formate für Konsolenprotokolle angewendet. Mit der Einführung einer neuen Formatierungs-API ist es jedoch sinnvoller, die Formatierung in den für sie spezifischen Optionen darzustellen. Diese Änderung verbessert die Trennung zwischen der Protokollierung und den Protokollformatierern.

Eingeführt in Version

5.0

Empfohlene Maßnahme

• Verwenden Sie die neue Eigenschaft ConsoleLoggerOptions.FormatterName anstelle der Eingenschaft ConsoleLoggerOptions.Format. Beispiel:

  loggingBuilder.AddConsole(options =>
  {
    options.FormatterName = ConsoleFormatterNames.Systemd;
  });
  

  Es gibt mehrere Unterschiede zwischen FormatterName und Format:

  • Format verfügt nur über zwei Optionen: Default und Systemd.
  • Bei FormatterName wird die Groß-/Kleinschreibung nicht beachtet. Außerdem kann die Eigenschaft eine beliebige Zeichenfolge darstellen. Die reservierten, integrierten Namen lauten Simple, Systemd und Json (.NET 5 und höher).
  • "Format": "Systemd" wird "FormatterName": "Systemd" zugeordnet.
  • "Format": "Default" wird "FormatterName": "Simple" zugeordnet.

• Verwenden Sie für die Eigenschaften DisableColors, IncludeScopes, TimestampFormat und UseUtcTimestamp stattdessen die entsprechende Eigenschaft in den neuen Typen ConsoleFormatterOptions, JsonConsoleFormatterOptions oder SimpleConsoleFormatterOptions. Beispielsweise ist SimpleConsoleFormatterOptions.ColorBehavior die entsprechende Einstellung für ConsoleLoggerOptions.DisableColors.

  Vorheriger Code:

  loggingBuilder.AddConsole(options =>
  {
      options.DisableColors = true;
  });
  

  Neuer Code:

  loggingBuilder.AddSimpleConsole(options =>
  {
      options.ColorBehavior = LoggerColorBehavior.Disabled;
  });
  

In den beiden folgenden JSON-Codeausschnitten wird gezeigt, wie sich die Konfigurationsdatei ändert. Alte Konfigurationsdatei:

{
  "Logging": {
    "LogLevel": {
      "Default": "None",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },

    "Console": {
      "LogLevel": {
        "Default": "Information"
      },
      "Format": "Systemd",
      "IncludeScopes": true,
      "TimestampFormat": "HH:mm:ss",
      "UseUtcTimestamp": true
    }
  },
  "AllowedHosts": "*"
}

Neue Konfigurationsdatei:

{
  "Logging": {
    "LogLevel": {
      "Default": "None",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },

    "Console": {
      "LogLevel": {
        "Default": "Information"
      },
      "FormatterName": "Systemd",
      "FormatterOptions": {
        "IncludeScopes": true,
        "TimestampFormat": "HH:mm:ss",
        "UseUtcTimestamp": true
      }
    }
  },
  "AllowedHosts": "*"
}

Betroffene APIs

• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp
• Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format