Устаревшие свойства ConsoleLoggerOptions

Тип Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat и некоторые свойства ConsoleLoggerOptions являются устаревшими.

Описание изменения

Начиная с .NET 5 тип Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat и несколько свойств ConsoleLoggerOptions являются устаревшими. Устаревшие свойства:

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

Эти свойства теперь доступны в отдельных новых форматировщиках.

Причина изменения

Свойство Format является типом перечисления, который не может представлять пользовательский форматировщик.

Остальные свойства были заданы в ConsoleLoggerOptions и применены к обоим встроенным форматам для журналов консоли. Но с введением нового API форматировщика будет логичным, если форматирование будет представлено в параметрах, относящихся к форматировщику. Это изменение обеспечивает лучшее разделение средств ведения журнала и связанных форматировщиков.

Представленные версии

5,0

Рекомендуемое действие

• Используйте новое свойство ConsoleLoggerOptions.FormatterName вместо свойства ConsoleLoggerOptions.Format. Например:

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

  Есть несколько различий между FormatterName и Format:

  • Format имеет только два возможных параметра: Default и Systemd.
  • FormatterName не учитывает регистр и может быть любой строкой. Зарезервированные встроенные имена — это Simple, Systemd и Json (.NET 5 и выше).
  • "Format": "Systemd" сопоставляется "FormatterName": "Systemd".
  • "Format": "Default" сопоставляется "FormatterName": "Simple".

• Для свойств DisableColors, IncludeScopes, TimestampFormat и UseUtcTimestamp используйте соответствующее свойство в новых типах ConsoleFormatterOptions, JsonConsoleFormatterOptionsили SimpleConsoleFormatterOptions. Например, соответствующим параметром для ConsoleLoggerOptions.DisableColors является SimpleConsoleFormatterOptions.ColorBehavior.

  Предыдущий код:

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

  Новый код:

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

В следующих двух фрагментах кода JSON показано, как изменяется файл конфигурации. Старый файл конфигурации:

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

Новый файл конфигурации:

{
  "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

• 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