Proprietà obsolete in ConsoleLoggerOptions

Il tipo Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat e alcune proprietà in ConsoleLoggerOptions sono ormai obsolete.

Descrizione delle modifiche

A partire da .NET 5, il tipo Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat e diverse proprietà in ConsoleLoggerOptions sono obsolete. Le proprietà obsolete sono le seguenti:

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

Con l'introduzione dei nuovi formattatori, queste proprietà sono ora disponibili nei singoli formattatori.

Motivo della modifica

La proprietà Format è un tipo di enumerazione, che non può rappresentare un formattatore personalizzato.

Le proprietà rimanenti sono state impostate su ConsoleLoggerOptions e vengono applicate a entrambi i formati predefiniti per i log della console. Tuttavia, con l'introduzione di una nuova API formattatore, è più opportuno rappresentare la formattazione nelle opzioni specifiche del formattatore. Questa modifica garantisce una migliore separazione tra il logger e i formattatori del logger.

Versione di introduzione

5.0

Azione consigliata

• Utilizzare la nuova proprietà ConsoleLoggerOptions.FormatterName al posto della proprietà ConsoleLoggerOptions.Format. Ad esempio:

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

  Esistono numerose differenze tra FormatterName e Format:

  • Format include solo due opzioni possibili: Default e Systemd.
  • FormatterName non fa distinzione tra maiuscole e minuscole e può essere qualsiasi stringa. I nomi riservati predefiniti sono Simple, Systemd e Json (.NET 5 e versioni successive).
  • "Format": "Systemd" esegue il mapping a "FormatterName": "Systemd".
  • "Format": "Default" esegue il mapping a "FormatterName": "Simple".

• Per le proprietà DisableColors, IncludeScopes, TimestampFormat e UseUtcTimestamp, usare invece la proprietà corrispondente nei nuovi tipi ConsoleFormatterOptions, JsonConsoleFormatterOptions o SimpleConsoleFormatterOptions. Ad esempio, l'impostazione corrispondente per ConsoleLoggerOptions.DisableColors è SimpleConsoleFormatterOptions.ColorBehavior.

  Codice precedente:

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

  Nuovo codice:

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

I due frammenti JSON seguenti mostrano come cambia il file di configurazione. File di configurazione precedente:

{
  "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": "*"
}

Nuovo file di configurazione:

{
  "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": "*"
}

API interessate

• 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