More STJ updates for .NET 9 (#43168)

Author: gewarren

docs/core/whats-new/dotnet-9/libraries.md

@@ -499,22 +499,11 @@ For more information, see [JSON schema exporter](../../../standard/serialization
 
 <xref:System.Text.Json> now recognizes nullability annotations of properties and can be configured to enforce those during serialization and deserialization using the <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> flag.
 
-The following code shows how to set the option (the `Book` type definition is shown in the previous section):
+The following code shows how to set the option:
 
 :::code language="csharp" source="../snippets/dotnet-9/csharp/Serialization.cs" id="RespectNullable":::
 
-> [!NOTE]
-> Due to how nullability annotations are represented in IL, the feature is restricted to annotations of non-generic properties.
-
-You can also enable this setting globally using the `System.Text.Json.Serialization.RespectNullableAnnotationsDefault` feature switch in your project file (for example, _.csproj_ file):
-
-```xml
-<ItemGroup>
-  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectNullableAnnotationsDefault" Value="true" />
-</ItemGroup>
-```
-
-You can configure nullability at an individual property level using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsGetNullable> and <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsSetNullable> properties.
+For more information, see [Respect nullable annotations](../../../standard/serialization/system-text-json/nullable-annotations.md).
 
 ### Require non-optional constructor parameters
 
@@ -528,15 +517,7 @@ The `MyPoco` type is defined as follows:
 
 :::code language="csharp" source="../snippets/dotnet-9/csharp/Serialization.cs" id="Poco":::
 
-You can also enable this setting globally using the `System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault` feature switch in your project file (for example, _.csproj_ file):
-
-```xml
-<ItemGroup>
-  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" Value="true" />
-</ItemGroup>
-```
-
-As with earlier versions of <xref:System.Text.Json>, you can configure whether individual properties are required using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType> property.
+For more information, see [Non-optional constructor parameters](../../../standard/serialization/system-text-json/required-properties.md#non-optional-constructor-parameters).
 
 ### Order JsonObject properties
 
@@ -562,6 +543,8 @@ enum MyEnum
 }
 ```
 
+For more information, see [Custom enum member names](../../../standard/serialization/system-text-json/customize-properties.md#custom-enum-member-names).
+
 ### Stream multiple JSON documents
 
 <xref:System.Text.Json.Utf8JsonReader?displayProperty=nameWithType> now supports reading multiple, whitespace-separated JSON documents from a single buffer or stream. By default, the reader throws an exception if it detects any non-whitespace characters that are trailing the first top-level document. You can change this behavior using the <xref:System.Text.Json.JsonReaderOptions.AllowMultipleValues> flag.

docs/core/whats-new/snippets/dotnet-9/csharp/Serialization.cs

@@ -64,23 +64,6 @@ public static void RunIt()
         // </PropertyOrder>
     }
 
-    public static void RunIt2()
-    {
-        // <RespectNullable>
-        JsonSerializerOptions options = new() { RespectNullableAnnotations = true };
-
-        // Throws exception: System.Text.Json.JsonException: The property or field
-        // 'Title' on type 'Serialization+Book' doesn't allow getting null values.
-        // Consider updating its nullability annotation.
-        JsonSerializer.Serialize(new Book { Title = null! }, options);
-
-        // Throws exception: System.Text.Json.JsonException: The property or field
-        // 'Title' on type 'Serialization+Book' doesn't allow setting null values.
-        // Consider updating its nullability annotation. 
-        JsonSerializer.Deserialize<Book>("""{ "Title" : null }""", options);
-        // </RespectNullable>
-    }
-
     public static void RunIt3()
     {
         // <RespectRequired>
@@ -105,3 +88,30 @@ public class Book
     record MyPoco(string Value);
     // </Poco>
 }
+
+public static class Serialization2
+{
+    // <RespectNullable>
+    public static void RunIt()
+    {
+        JsonSerializerOptions options = new() { RespectNullableAnnotations = true };
+
+        // Throws exception: System.Text.Json.JsonException: The property or field
+        // 'Title' on type 'Serialization+Book' doesn't allow getting null values.
+        // Consider updating its nullability annotation.
+        JsonSerializer.Serialize(new Book { Title = null! }, options);
+
+        // Throws exception: System.Text.Json.JsonException: The property or field
+        // 'Title' on type 'Serialization+Book' doesn't allow setting null values.
+        // Consider updating its nullability annotation.
+        JsonSerializer.Deserialize<Book>("""{ "Title" : null }""", options);
+    }
+
+    public class Book
+    {
+        public required string Title { get; set; }
+        public string? Author { get; set; }
+        public int PublishYear { get; set; }
+    }
+    // </RespectNullable>
+}

docs/fundamentals/toc.yml

@@ -737,6 +737,8 @@ items:
                         href: ../standard/serialization/system-text-json/deserialization.md
                       - name: Require JSON properties
                         href: ../standard/serialization/system-text-json/required-properties.md
+                      - name: Respect nullable annotations
+                        href: ../standard/serialization/system-text-json/nullable-annotations.md
                       - name: Allow invalid JSON
                         href: ../standard/serialization/system-text-json/invalid-json.md
                       - name: Handle missing members

docs/standard/serialization/system-text-json/customize-properties.md

@@ -1,7 +1,7 @@
 ---
 title: How to customize property names and values with System.Text.Json
 description: "Learn how to customize property names and values when serializing with System.Text.Json in .NET."
-ms.date: 10/16/2023
+ms.date: 10/22/2024
 zone_pivot_groups: dotnet-version
 no-loc: [System.Text.Json, Newtonsoft.Json]
 dev_langs:
@@ -21,7 +21,7 @@ ms.custom: vs-copilot-horizontal
 
 By default, property names and dictionary keys are unchanged in the JSON output, including case. Enum values are represented as numbers. And properties are serialized in the order they're defined. However, you can customize these behaviors by:
 
-- Specifying specific serialized property names.
+- Specifying specific serialized property and enum member names.
 - Using a built-in [naming policy](xref:System.Text.Json.JsonNamingPolicy), such as camelCase, snake_case, or kebab-case, for property names and dictionary keys.
 - Using a custom naming policy for property names and dictionary keys.
 - Serializing enum values as strings, with or without a naming policy.
@@ -156,18 +156,8 @@ Naming policies for dictionary keys apply to serialization only. If you deserial
 
 ## Enums as strings
 
-:::zone pivot="dotnet-8-0"
-
 By default, enums are serialized as numbers. To serialize enum names as strings, use the <xref:System.Text.Json.Serialization.JsonStringEnumConverter> or <xref:System.Text.Json.Serialization.JsonStringEnumConverter%601> converter. Only <xref:System.Text.Json.Serialization.JsonStringEnumConverter%601> is supported by the Native AOT runtime.
 
-:::zone-end
-
-:::zone pivot="dotnet-7-0,dotnet-6-0"
-
-By default, enums are serialized as numbers. To serialize enum names as strings, use the <xref:System.Text.Json.Serialization.JsonStringEnumConverter> converter.
-
-:::zone-end
-
 For example, suppose you need to serialize the following class that has an enum:
 
 :::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithEnum":::
@@ -203,7 +193,7 @@ The built-in <xref:System.Text.Json.Serialization.JsonStringEnumConverter> can d
 :::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumAsString.cs" id="Deserialize":::
 :::code language="vb" source="snippets/how-to/vb/RoundtripEnumAsString.vb" id="Deserialize":::
 
-:::zone pivot="dotnet-8-0"
+### JsonConverterAttribute
 
 You can also specify the converter to use by annotating your enum with <xref:System.Text.Json.Serialization.JsonConverterAttribute>. The following example shows how to specify the <xref:System.Text.Json.Serialization.JsonStringEnumConverter%601> (available in .NET 8 and later versions) by using the <xref:System.Text.Json.Serialization.JsonConverterAttribute> attribute. For example, suppose you need to serialize the following class that has an enum:
 
@@ -213,7 +203,7 @@ The following sample code serializes the enum names instead of the numeric value
 
 :::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumUsingConverterAttribute.cs" id="Serialize":::
 
-The resulting JSON looks like the following example:
+The resulting JSON looks like this:
 
 ```json
 {
@@ -223,9 +213,31 @@ The resulting JSON looks like the following example:
 }
 ```
 
-To use the converter with source generation, see [Serialize enum fields as strings](source-generation.md#serialize-enum-fields-as-strings).
+### Custom enum member names
+
+Starting in .NET 9, you can customize the names of individual enum members for types that are serialized as strings. To customize an enum member name, annotate it with the [JsonStringEnumMemberName attribute](xref:System.Text.Json.Serialization.JsonStringEnumMemberNameAttribute).
+
+For example, suppose you need to serialize the following class that has an enum with a custom member name:
+
+:::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithEnumCustomName":::
+
+The following sample code serializes the enum names instead of the numeric values:
 
-:::zone-end
+:::code language="csharp" source="snippets/how-to/csharp/SerializeEnumCustomName.cs" id="Serialize":::
+
+The resulting JSON looks like this:
+
+```json
+{
+  "Date": "2019-08-01T00:00:00-07:00",
+  "TemperatureCelsius": 25,
+  "Sky": "Partly cloudy"
+}
+```
+
+### Source generation
+
+To use the converter with source generation, see [Serialize enum fields as strings](source-generation.md#serialize-enum-fields-as-strings).
 
 ## Configure the order of serialized properties
 
@@ -272,7 +284,7 @@ The following example shows you how to use Copilot to modify existing code to cu
 
    using System.Text.Json;
    using System.Text.Json.Serialization;
-   
+
    public class Person
    {
        [JsonPropertyName("first_name")]

docs/standard/serialization/system-text-json/nullable-annotations.md

@@ -0,0 +1,89 @@
+---
+title: Respect nullable annotations
+description: "Learn how to configure serialization and deserialization to respect nullable annotations."
+ms.date: 10/22/2024
+no-loc: [System.Text.Json, Newtonsoft.Json]
+---
+# Respect nullable annotations
+
+Starting in .NET 9, <xref:System.Text.Json.JsonSerializer> has (limited) support for non-nullable reference type enforcement in both serialization and deserialization. You can toggle this support using the <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations?displayProperty=nameWithType> flag.
+
+For example, the following code snippet throws a <xref:System.Text.Json.JsonException> during serialization with a message like:
+
+> The property or field 'Name' on type 'Person' doesn't allow getting null values. Consider updating its nullability annotation.
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Serialization":::
+
+Similarly, <xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> enforces nullability on deserialization. The following code snippet throws a <xref:System.Text.Json.JsonException> during serialization with a message like:
+
+> The constructor parameter 'Name' on type 'Person' doesn't allow null values. Consider updating its nullability annotation.
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Deserialization":::
+
+> [!TIP]
+>
+> - You can configure nullability at an individual property level using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsGetNullable> and <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsSetNullable> properties.
+> - The C# compiler uses the [`[NotNull]`](xref:System.Diagnostics.CodeAnalysis.NotNullAttribute), [`[AllowNull]`](xref:System.Diagnostics.CodeAnalysis.AllowNullAttribute), [`[MaybeNull]`](xref:System.Diagnostics.CodeAnalysis.MaybeNullAttribute), and [`[DisallowNull]`](xref:System.Diagnostics.CodeAnalysis.DisallowNullAttribute) attributes to fine-tune annotations in getters and setters. These attributes are also recognized by this System.Text.Json feature. (For more information about the attributes, see [Attributes for null-state static analysis](../../../csharp/language-reference/attributes/nullable-analysis.md).)
+
+## Limitations
+
+Due to how non-nullable reference types are implemented, this feature comes with some important limitations. Familiarize yourself with these limitations before turning the feature on. The root of the issue is that reference type nullability has no first-class representation in intermediate language (IL). As such, the expressions `MyPoco` and `MyPoco?` are indistinguishable from the perspective of run-time reflection. While the compiler tries to make up for that by emitting attribute metadata (see [sharplab.io example](https://sharplab.io/#v2:D4AQTAjAsAULBOBTAxge3gEwAQFkCeACqmgBQgQAMWAcqgC7UCuANswMp3wCWAdgOYAaLOQoB+Gi2YBDAEbNEHbvwCUAbiA=)), this metadata is restricted to non-generic member annotations that are scoped to a particular type definition. This limitation is the reason that the flag only validates nullability annotations that are present on non-generic properties, fields, and constructor parameters. System.Text.Json does not support nullability enforcement on:
+
+- Top-level types, or the type that's passed when making the first `JsonSerializer.Deserialize()` or `JsonSerializer.Serialize()` call.
+- Collection element types&mdash;for example, the `List<string>` and `List<string?>` types are indistinguishable.
+- Any properties, fields, or constructor parameters that are generic.
+
+If you want to add nullability enforcement in these cases, either model your type to be a struct (since they don't admit null values), or author a custom converter that overrides its <xref:System.Text.Json.Serialization.JsonConverter`1.HandleNull> property to `true`.
+
+## Feature switch
+
+You can turn on the `RespectNullableAnnotations` setting globally using the `System.Text.Json.Serialization.RespectNullableAnnotationsDefault` feature switch. Add the following MSBuild item to your project file (for example, *.csproj* file):
+
+```xml
+<ItemGroup>
+  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectNullableAnnotationsDefault" Value="true" />
+</ItemGroup>
+```
+
+The `RespectNullableAnnotationsDefault` API was implemented as an opt-in flag in .NET 9 to avoid breaking existing applications. If you're writing a new application, it's highly recommended that you enable this flag in your code.
+
+## Relationship between nullable and optional parameters
+
+<xref:System.Text.Json.JsonSerializerOptions.RespectNullableAnnotations> doesn't extend enforcement to unspecified JSON values, because System.Text.Json treats required and non-nullable properties as orthogonal concepts. For example, the following code snippet doesn't throw an exception during deserialization:
+
+:::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="Unspecified":::
+
+This behavior stems from the C# language itself, where you can have required properties that are nullable:
+
+```csharp
+MyPoco poco = new() { Value = null }; // No compiler warnings.
+
+class MyPoco
+{
+    public required string? Value { get; set; }
+}
+```
+
+And you can also have optional properties that are non-nullable:
+
+```csharp
+class MyPoco
+{
+    public string Value { get; set; } = "default";
+}
+```
+
+The same orthogonality applies to constructor parameters:
+
+```csharp
+record MyPoco(
+    string RequiredNonNullable,
+    string? RequiredNullable,
+    string OptionalNonNullable = "default",
+    string? OptionalNullable = "default"
+    );
+```
+
+## See also
+
+- [Non-optional constructor parameters](required-properties.md#non-optional-constructor-parameters)