JSON source gen breaking change (#26222)

Author: gewarren

.openpublishing.redirection.json

@@ -250,6 +250,11 @@
             "source_path": "docs/core/compatibility/code-analysis.md",
             "redirect_url": "/dotnet/core/compatibility/code-analysis/5.0/ca1416-platform-compatibility-analyzer"
         },
+        {
+            "source_path": "docs/core/compatibility/core-libraries/6.0/jsonserializer-source-generator-overloads.md",
+            "redirect_url": "/dotnet/core/compatibility/serialization/6.0/jsonserializer-source-generator-overloads",
+            "redirect_document_id": true
+        },
         {
             "source_path": "docs/core/compatibility/interop.md",
             "redirect_url": "/dotnet/core/compatibility/interop/5.0/built-in-support-for-winrt-removed"

docs/core/compatibility/6.0.md

@@ -47,7 +47,6 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 | [FileStream no longer synchronizes file offset with OS](core-libraries/6.0/filestream-doesnt-sync-offset-with-os.md) | Preview 4 |
 | [FileStream.Position updates after ReadAsync or WriteAsync completes](core-libraries/6.0/filestream-position-updates-after-readasync-writeasync-completion.md) | Preview 4 |
 | [New diagnostic IDs for obsoleted APIs](core-libraries/6.0/diagnostic-id-change-for-obsoletions.md) | Preview 5 |
-| [New JsonSerializer source generator overloads](core-libraries/6.0/jsonserializer-source-generator-overloads.md) | Preview 6 |
 | [New nullable annotation in AssociatedMetadataTypeTypeDescriptionProvider](core-libraries/6.0/nullable-ref-type-annotations-added.md) | RC 2 |
 | [New System.Linq.Queryable method overloads](core-libraries/6.0/additional-linq-queryable-method-overloads.md) | Preview 3-4 |
 | [Older framework versions dropped from package](core-libraries/6.0/older-framework-versions-dropped.md) | Preview 5 |
@@ -106,7 +105,9 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 
 | Title | Preview introduced |
 | - | - |
+| [JSON source-generation API refactoring](serialization/6.0/json-source-gen-api-refactor.md) | RC 2 |
 | [JsonNode no longer supports C# `dynamic` type](serialization/6.0/jsonnode-dynamic-type.md) | Preview 7 |
+| [New JsonSerializer source generator overloads](serialization/6.0/jsonserializer-source-generator-overloads.md) | Preview 6 |
 
 ## Windows Forms
 

docs/core/compatibility/serialization/6.0/json-source-gen-api-refactor.md

@@ -0,0 +1,43 @@
+---
+title: "Breaking change: JSON source-generation API refactoring"
+description: Learn about the .NET 6.0 breaking change where the APIs called by JSON source generator output were refactored.
+ms.date: 09/22/2021
+---
+# JSON source-generation API refactoring
+
+The APIs that the output of the JSON source generator calls have been refactored. The refactoring makes them easier to extend with new features in the future. Projects that explicitly use the JSON source generator and were compiled with .NET 6 RC 1 or earlier will fail with run-time exceptions when run on the .NET 6 RC 2 runtime.
+
+## Previous behavior
+
+Projects that were compiled using the .NET 6 RC 1 or earlier version of the System.Text.Json source generator and library run as expected.
+
+## New behavior
+
+Projects that were compiled using the .NET 6 RC 1 version of the System.Text.Json source generator and library fail when run against the .NET 6 RC 2 runtime. Projects that are recompiled with the RC 2 SDK work as expected.
+
+## Version introduced
+
+6.0 RC 2
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility).
+
+## Reason for change
+
+This change was introduced to make it easier to extend the source-generator implementation with features in the future. For more information, see [dotnet/runtime#59243](https://github.com/dotnet/runtime/pull/59243).
+
+## Recommended action
+
+Recompile your app using the RC 2 SDK.
+
+## Affected APIs
+
+- <xref:System.Text.Json.Serialization.JsonSerializerContext?displayProperty=fullName>
+- <xref:System.Text.Json.Serialization.JsonSerializableAttribute?displayProperty=fullName>
+- <xref:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute?displayProperty=fullName>
+- <xref:System.Text.Json.Serialization.Metadata?displayProperty=fullName> (not intended for direct use)
+
+## See also
+
+- [How to use source generation in System.Text.Json](../../../../standard/serialization/system-text-json-source-generation.md)

docs/core/compatibility/core-libraries/6.0/jsonserializer-source-generator-overloads.md renamed to docs/core/compatibility/serialization/6.0/jsonserializer-source-generator-overloads.md

@@ -77,8 +77,6 @@ items:
           href: core-libraries/6.0/filestream-position-updates-after-readasync-writeasync-completion.md
         - name: New diagnostic IDs for obsoleted APIs
           href: core-libraries/6.0/diagnostic-id-change-for-obsoletions.md
-        - name: New JsonSerializer source generator overloads
-          href: core-libraries/6.0/jsonserializer-source-generator-overloads.md
         - name: New nullable annotation in AssociatedMetadataTypeTypeDescriptionProvider
           href: core-libraries/6.0/nullable-ref-type-annotations-added.md
         - name: New Queryable method overloads
@@ -139,6 +137,14 @@ items:
           href: sdk/6.0/outputtype-not-set-automatically.md
         - name: RuntimeIdentifier warning if self-contained is unspecified
           href: sdk/6.0/runtimeidentifier-self-contained.md
+      - name: Serialization
+        items:
+        - name: JSON source-generation API refactoring
+          href: serialization/6.0/json-source-gen-api-refactor.md
+        - name: JsonNode no longer supports C# `dynamic`
+          href: serialization/6.0/jsonnode-dynamic-type.md
+        - name: New JsonSerializer source generator overloads
+          href: serialization/6.0/jsonserializer-source-generator-overloads.md
       - name: Windows Forms
         items:
         - name: APIs throw ArgumentNullException
@@ -579,8 +585,6 @@ items:
           href: core-libraries/6.0/filestream-position-updates-after-readasync-writeasync-completion.md
         - name: New diagnostic IDs for obsoleted APIs
           href: core-libraries/6.0/diagnostic-id-change-for-obsoletions.md
-        - name: New JsonSerializer source generator overloads
-          href: core-libraries/6.0/jsonserializer-source-generator-overloads.md
         - name: New nullable annotation in AssociatedMetadataTypeTypeDescriptionProvider
           href: core-libraries/6.0/nullable-ref-type-annotations-added.md
         - name: New Queryable method overloads
@@ -803,8 +807,12 @@ items:
       items:
       - name: .NET 6
         items:
+        - name: JSON source-generation API refactoring
+          href: serialization/6.0/json-source-gen-api-refactor.md
         - name: JsonNode no longer supports C# `dynamic`
           href: serialization/6.0/jsonnode-dynamic-type.md
+        - name: New JsonSerializer source generator overloads
+          href: serialization/6.0/jsonserializer-source-generator-overloads.md
       - name: .NET 5
         items:
         - name: BinaryFormatter.Deserialize rewraps exceptions

docs/core/compatibility/toc.yml

@@ -68,7 +68,7 @@ The following table shows which options specified by `JsonSerializerOptions` are
 | <xref:System.Text.Json.JsonSerializerOptions.ReferenceHandler>         | ❌                          |
 | <xref:System.Text.Json.JsonSerializerOptions.WriteIndented> \*         | ✔️                         |
 
-\* Some `Serialize` methods let you pass in a `Utf8JsonWriter` instance. In that case, you can set the `Encoder` and `WriteIndented` options by using <xref:System.Text.Json.JsonWriterOptions.Indented?displayProperty=nameWithType> and <xref:System.Text.Json.JsonWriterOptions.Indented?displayProperty=nameWithType>.
+\* Some `Serialize` methods let you pass in a `Utf8JsonWriter` instance. In that case, you can set the `Encoder` and `WriteIndented` options by using <xref:System.Text.Json.JsonWriterOptions.Encoder?displayProperty=nameWithType> and <xref:System.Text.Json.JsonWriterOptions.Indented?displayProperty=nameWithType>.
 
 The following table shows which attributes are supported by the optimized serialization code: