Obsolete properties on ConsoleLoggerOptions

The Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat type and some properties on ConsoleLoggerOptions are now obsolete.

Change description

Starting in .NET 5, the Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat type and several properties on ConsoleLoggerOptions are obsolete. The obsolete properties are:

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

With the introduction of new formatters, these properties are now available on the individual formatters.

Reason for change

The Format property is an enumeration type, which cannot represent a custom formatter.

The remaining properties were set on ConsoleLoggerOptions and applied to both of the built-in formats for console logs. However, with the introduction of a new formatter API, it makes more sense for formatting to be represented on the formatter-specific options. This change provides better separation between the logger and logger formatters.

Version introduced

5.0

Recommended action

• Use the new ConsoleLoggerOptions.FormatterName property in place of the ConsoleLoggerOptions.Format property. For example:

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

  There are several differences between FormatterName and Format:

  • Format has only two possible options: Default and Systemd.
  • FormatterName is case insensitive and can be any string. The reserved, built-in names are Simple, Systemd, and Json (.NET 5 and later).
  • "Format": "Systemd" maps to "FormatterName": "Systemd".
  • "Format": "Default" maps to "FormatterName": "Simple".

• For the DisableColors, IncludeScopes, TimestampFormat, and UseUtcTimestamp properties, use the corresponding property on the new ConsoleFormatterOptions, JsonConsoleFormatterOptions, or SimpleConsoleFormatterOptions types instead. For example, the corresponding setting for ConsoleLoggerOptions.DisableColors is SimpleConsoleFormatterOptions.ColorBehavior.

  Previous code:

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

  New code:

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

The following two JSON snippets show how the configuration file changes. Old configuration file:

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

New configuration file:

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

Affected 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