Add console logger breaking changes

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)]
 
 ***

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)]
 
 ***

includes/core-changes/corefx/5.0/obsolete-consoleloggeroptions-properties.md

@@ -0,0 +1,129 @@
+### Obsolete properties on ConsoleLoggerOptions
+
+The <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat?displayProperty=nameWithType> type and some properties on <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions> are now obsolete.
+
+#### Change description
+
+Starting in .NET 5.0, the <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerFormat?displayProperty=nameWithType> type and several properties on <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions> are obsolete. The obsolete properties are:
+
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors?displayProperty=nameWithType>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes?displayProperty=nameWithType>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat?displayProperty=nameWithType>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp?displayProperty=nameWithType>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format?displayProperty=nameWithType>
+
+With the introduction of new formatters, these properties are now available on the individual formatters.
+
+#### Reason for change
+
+The <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format> property is an enumeration type, which cannot represent a custom formatter.
+
+The remaining properties were set on <xref:Microsoft.Extensions.Logging.Console.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 Preview 8
+
+#### Recommended action
+
+- Use the new <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.FormatterName?displayProperty=nameWithType> property in place of the <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format?displayProperty=nameWithType> property. For example:
+
+  ```csharp
+  loggingBuilder.AddConsole(options =>
+  {
+    options.FormatterName = ConsoleFormatterNames.Systemd;
+  });
+  ```
+
+  There are several differences between <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.FormatterName> and <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format>:
+
+  - <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format> has only two possible options: `Default` and `Systemd`.
+  - <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.FormatterName> 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 <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors>, <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes>, <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat>, and <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp> properties, use the corresponding property on the new <xref:Microsoft.Extensions.Logging.Console.ConsoleFormatterOptions>, <xref:Microsoft.Extensions.Logging.Console.JsonConsoleFormatterOptions>, or <xref:Microsoft.Extensions.Logging.Console.SimpleConsoleFormatterOptions> 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
+
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors?displayProperty=fullName>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes?displayProperty=fullName>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat?displayProperty=fullName>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp?displayProperty=fullName>
+- <xref:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format?displayProperty=fullName>
+
+<!--
+
+#### Affected APIs
+
+- `P:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.DisableColors`
+- `P:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.IncludeScopes`
+- `P:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.TimestampFormat`
+- `P:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.UseUtcTimestamp`
+- `P:Microsoft.Extensions.Logging.Console.ConsoleLoggerOptions.Format`
+
+-->