diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index 3763b2e30995d..006adef1f4dab 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -150,6 +150,7 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v ## Core .NET libraries +- [Obsolete properties on ConsoleLoggerOptions](#obsolete-properties-on-consoleloggeroptions) - [Hardware intrinsic IsSupported checks may differ for nested types](#hardware-intrinsic-issupported-checks-may-differ-for-nested-types) - [Parameter names changed in reference assemblies](#parameter-names-changed-in-reference-assemblies) - [URI paths with non-ASCII characters parse correctly on Unix](#uri-paths-with-non-ascii-characters-parse-correctly-on-unix) @@ -167,6 +168,10 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v - [CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist](#countersetcreatecountersetinstance-now-throws-invalidoperationexception-if-instance-already-exists) - [Microsoft.DotNet.PlatformAbstractions package removed](#microsoftdotnetplatformabstractions-package-removed) +[!INCLUDE [obsolete-consoleloggeroptions-properties](../../../includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md)] + +*** + [!INCLUDE [hardware-instrinsics-issupported-checks](../../../includes/core-changes/corefx/5.0/hardware-instrinsics-issupported-checks.md)] *** diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index 026c0f9d87490..174ed24bfaa6d 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -11,6 +11,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [Obsolete properties on ConsoleLoggerOptions](#obsolete-properties-on-consoleloggeroptions) | 5.0 | | [Hardware intrinsic IsSupported checks may differ for nested types](#hardware-intrinsic-issupported-checks-may-differ-for-nested-types) | 5.0 | | [Parameter names changed in reference assemblies](#parameter-names-changed-in-reference-assemblies) | 5.0 | | [URI paths with non-ASCII characters parse correctly on Unix](#uri-paths-with-non-ascii-characters-parse-correctly-on-unix) | 5.0 | @@ -46,6 +47,10 @@ The following breaking changes are documented on this page: ## .NET 5.0 +[!INCLUDE [obsolete-consoleloggeroptions-properties](../../../includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md)] + +*** + [!INCLUDE [hardware-instrinsics-issupported-checks](../../../includes/core-changes/corefx/5.0/hardware-instrinsics-issupported-checks.md)] *** diff --git a/includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md b/includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md new file mode 100644 index 0000000000000..803c5a3d48efc --- /dev/null +++ b/includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md @@ -0,0 +1,129 @@ +### Obsolete properties on ConsoleLoggerOptions + +The type and some properties on are now obsolete. + +#### Change description + +Starting in .NET 5.0, the type and several properties on are obsolete. The obsolete properties are: + +- +- +- +- +- + +With the introduction of new formatters, these properties are now available on the individual formatters. + +#### Reason for change + +The property is an enumeration type, which cannot represent a custom formatter. + +The remaining properties were set on 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 Preview 8 + +#### Recommended action + +- Use the new property in place of the property. For example: + + ```csharp + loggingBuilder.AddConsole(options => + { + options.FormatterName = ConsoleFormatterNames.Systemd; + }); + ``` + + There are several differences between and : + + - has only two possible options: `Default` and `Systemd`. + - is case insensitive and can be any string. The reserved, built-in names are `Simple`, `Systemd`, and `Json` (.NET 5.0 and later). + - `"Format": "Systemd"` maps to `"FormatterName": "Systemd"`. + - `"Format": "Default"` maps to `"FormatterName": "Simple"`. + +- For the , , , and properties, use the corresponding property on the new , , or types instead. For example: + + ```csharp + loggingBuilder.AddSimpleConsole(options => + { + options.DisableColors = true; + }); + ``` + +The following two JSON snippets show how the configuration file changes. Old configuration file: + +```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": "*" +} +``` + +New configuration file: + +```json +{ + "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": "*" +} +``` + +#### Category + +- Core .NET libraries +- ASP.NET + +#### Affected APIs + +- +- +- +- +- + +