Propriedades obsoletas em ConsoleLoggerOptions

O tipo Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat e algumas propriedades em ConsoleLoggerOptions agora estão obsoletos.

Descrição das alterações

Do .NET 5 em diante, o tipo Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat e várias propriedades em ConsoleLoggerOptions estão obsoletos. As propriedades obsoletas são:

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

Com a introdução de novos formatadores, essas propriedades agora estão disponíveis nos formatadores individuais.

Motivo da alteração

A propriedade Format é um tipo de enumeração, que não pode representar um formatador personalizado.

As propriedades restantes foram definidas em ConsoleLoggerOptions e aplicadas a ambos os formatos internos de logs de console. No entanto, com a introdução de uma nova API de formatador, faz mais sentido que a formatação seja representada nas opções específicas do formatador. Essa alteração fornece uma melhor separação entre o agente e os formatadores do agente.

Versão introduzida

5,0

Ação recomendada

• Use a nova propriedade ConsoleLoggerOptions.FormatterName no lugar da propriedade ConsoleLoggerOptions.Format. Por exemplo:

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

  Há várias diferenças entre FormatterName e Format:

  • Format tem apenas duas opções possíveis: Default e Systemd.
  • FormatterName não diferencia maiúsculas de minúsculas e pode ser qualquer cadeia de caracteres. Os nomes reservados e internos são Simple, Systemd e Json (.NET 5 e versão posterior).
  • O "Format": "Systemd" é mapeado para "FormatterName": "Systemd".
  • O "Format": "Default" é mapeado para "FormatterName": "Simple".

• Para as propriedades DisableColors, IncludeScopes, TimestampFormat e UseUtcTimestamp, em vez disso use a propriedade correspondente dos novos tipos ConsoleFormatterOptions, JsonConsoleFormatterOptions ou SimpleConsoleFormatterOptions. Por exemplo, a configuração correspondente para ConsoleLoggerOptions.DisableColors é SimpleConsoleFormatterOptions.ColorBehavior.

  Código anterior:

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

  Novo código:

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

Os dois snippets JSON a seguir mostram como o arquivo de configuração é alterado. Arquivo de configuração antigo:

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

Novo arquivo de configuração:

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

APIs afetadas

• 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