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
andSystemd
. - FormatterName is case insensitive and can be any string. The reserved, built-in names are
Simple
,Systemd
, andJson
(.NET 5 and later). "Format": "Systemd"
maps to"FormatterName": "Systemd"
."Format": "Default"
maps to"FormatterName": "Simple"
.
- Format has only two possible options:
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