non-optional constructor params

Author: gewarren

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

@@ -528,15 +528,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
 

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

@@ -1,80 +1,62 @@
 ---
 title: Require properties for deserialization
 description: "Learn how to mark properties as required for deserialization to succeed."
-ms.date: 09/21/2022
+ms.date: 10/22/2024
 no-loc: [System.Text.Json, Newtonsoft.Json]
 ---
 # Required properties
 
-Starting in .NET 7, you can mark certain properties to signify that they must be present in the JSON payload for deserialization to succeed. If one or more of these required properties is not present, the <xref:System.Text.Json.JsonSerializer.Deserialize%2A?displayProperty=nameWithType> methods throw a <xref:System.Text.Json.JsonException>.
+You can mark certain properties to signify that they must be present in the JSON payload for deserialization to succeed. Similarly, you can set an option to specify that all non-optional constructor parameters are present in the JSON payload. If one or more of these required properties is not present, the <xref:System.Text.Json.JsonSerializer.Deserialize%2A?displayProperty=nameWithType> methods throw a <xref:System.Text.Json.JsonException>.
 
 There are three ways to mark a property or field as required for JSON deserialization:
 
-- By adding the [required modifier](../../../csharp/language-reference/keywords/required.md), which is new in C# 11.
-- By annotating it with <xref:System.Text.Json.Serialization.JsonRequiredAttribute>, which is new in .NET 7.
-- By modifying the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType> property of the contract model, which is new in .NET 7.
+- By adding the [`required` modifier](../../../csharp/language-reference/keywords/required.md).
+- By annotating it with <xref:System.Text.Json.Serialization.JsonRequiredAttribute>.
+- By modifying the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType> property of the contract model.
 
-From the serializer's perspective, these two demarcations are equivalent and both map to the same piece of metadata, which is <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType>. In most cases, you'd simply use the built-in C# keyword. However, in the following cases, you should use <xref:System.Text.Json.Serialization.JsonRequiredAttribute> instead:
+To specify that all non-optional constructor parameters are required for JSON deserialization, set the <xref:System.Text.Json.JsonSerializerOptions.RespectRequiredConstructorParameters?displayProperty=nameWithType> option (or, for source generation, <xref:System.Text.Json.Serialization.JsonSourceGenerationOptionsAttribute.RespectRequiredConstructorParameters> property) to `true`. For more information, see the [Non-optional constructor parameters](#non-optional-constructor-parameters) section.
+
+From the serializer's perspective, the C# `required` modifier and [`[JsonRequired]`](xref:System.Text.Json.Serialization.JsonRequiredAttribute) attribute are equivalent, and both map to the same piece of metadata, which is <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType>. In most cases, you'd simply use the built-in C# keyword. However, in the following cases, you should use <xref:System.Text.Json.Serialization.JsonRequiredAttribute> instead:
 
 - If you're using a programming language other than C# or a down-level version of C#.
 - If you only want the requirement to apply to JSON deserialization.
 - If you're using `System.Text.Json` serialization in [source generation](source-generation-modes.md#metadata-based-mode) mode. In this case, your code won't compile if you use the `required` modifier, as source generation occurs at compile time.
 
 The following code snippet shows an example of a property modified with the `required` keyword. This property must be present in the JSON payload for deserialization to succeed.
 
-```csharp
-using System.Text.Json;
+:::code language="csharp" source="snippets/required-properties/RequiredProperties.cs" id="Keyword":::
 
-// The following line throws a JsonException at run time.
-Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
+Alternatively, you can use <xref:System.Text.Json.Serialization.JsonRequiredAttribute>:
 
-public class Person
-{
-    public required string Name { get; set; }
-    public int Age { get; set; }
-}
-```
+:::code language="csharp" source="snippets/required-properties/RequiredProperties.cs" id="Attribute":::
 
-Alternatively, you can use <xref:System.Text.Json.Serialization.JsonRequiredAttribute>:
+It's also possible to control whether a property is required via the contract model using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType> property:
 
-```csharp
-using System.Text.Json;
+:::code language="csharp" source="snippets/required-properties/RequiredProperties.cs" id="ContractModel":::
+
+## Non-optional constructor parameters
 
-// The following line throws a JsonException at run time.
-Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
+Prior to .NET 9, constructor-based deserialization treated all constructor parameters as optional, as the following example shows:
 
-public class Person
-{
-    [JsonRequired]
-    public string Name { get; set; }
-    public int Age { get; set; }
-}
+```csharp
+var result = JsonSerializer.Deserialize<Person>("{}");
+Console.WriteLine(result); // Person { Name = , Age = 0 }
+
+record Person(string Name, int Age);
 ```
 
-It's also possible to control whether a property is required via the contract model using the <xref:System.Text.Json.Serialization.Metadata.JsonPropertyInfo.IsRequired?displayProperty=nameWithType> property:
+Starting in .NET 9, you can set the <xref:System.Text.Json.JsonSerializerOptions.RespectRequiredConstructorParameters> flag to treat non-optional constructor parameters as required.
 
-```csharp
-var options = new JsonSerializerOptions
-{
-    TypeInfoResolver = new DefaultJsonTypeInfoResolver
-    {
-        Modifiers =
-        {
-            static typeInfo =>
-            {
-                if (typeInfo.Kind != JsonTypeInfoKind.Object)
-                    return;
-
-                foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
-                {
-                    // Strip IsRequired constraint from every property.
-                    propertyInfo.IsRequired = false;
-                }
-            }
-        }
-    }
-};
-
-// Deserialization now succeeds even though the Name property isn't in the JSON payload.
-JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);
+:::code language="csharp" source="snippets/required-properties/RequiredProperties.cs" id="RequiredConstrParams":::
+
+### Feature switch
+
+You can turn on the `RespectRequiredConstructorParameters` setting globally using the `System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault` feature switch. Add the following MSBuild item to your project file (for example, *.csproj* file):
+
+```xml
+<ItemGroup>
+  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" Value="true" />
+</ItemGroup>
 ```
+
+The `RespectRequiredConstructorParametersDefault` 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.

docs/standard/serialization/system-text-json/snippets/required-properties/Program.cs

@@ -0,0 +1,4 @@
+//RequiredProperties.RunIt();
+//RequiredProperties2.RunIt();
+//RequiredProperties3.RunIt();
+RequiredProperties4.RunIt();

docs/standard/serialization/system-text-json/snippets/required-properties/Project.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>

docs/standard/serialization/system-text-json/snippets/required-properties/RequiredProperties.cs

@@ -0,0 +1,96 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using System.Text.Json.Serialization.Metadata;
+
+public static class RequiredProperties
+{
+    // <Keyword>
+    public static void RunIt()
+    {
+        // The following line throws a JsonException at run time.
+        Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
+    }
+
+    public class Person
+    {
+        public required string Name { get; set; }
+        public int Age { get; set; }
+    }
+    // </Keyword>
+}
+
+public static class RequiredProperties2
+{
+    // <Attribute>
+    public static void RunIt()
+    {
+        // The following line throws a JsonException at run time.
+        Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
+    }
+
+    public class Person
+    {
+        [JsonRequired]
+        public string Name { get; set; }
+        public int Age { get; set; }
+    }
+    // </Attribute>
+}
+
+public static class RequiredProperties3
+{
+    // <ContractModel>
+    public static void RunIt()
+    {
+        var options = new JsonSerializerOptions
+        {
+            TypeInfoResolver = new DefaultJsonTypeInfoResolver
+            {
+                Modifiers =
+                {
+                    static typeInfo =>
+                    {
+                        if (typeInfo.Kind != JsonTypeInfoKind.Object)
+                            return;
+
+                        foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
+                        {
+                            // Strip IsRequired constraint from every property.
+                            propertyInfo.IsRequired = false;
+                        }
+                    }
+                }
+            }
+        };
+
+        // Deserialization succeeds even though
+        // the Name property isn't in the JSON payload.
+        JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);
+    }
+
+    public class Person
+    {
+        public required string Name { get; set; }
+        public int Age { get; set; }
+    }
+    // </ContractModel>
+}
+
+public static class RequiredProperties4
+{
+    // <RequiredConstrParams>
+    public static void RunIt()
+    {
+        JsonSerializerOptions options = new()
+        {
+            RespectRequiredConstructorParameters = true
+        };
+        string json = """{"Age": 42}""";
+
+        // The following line throws a JsonException at run time.
+        JsonSerializer.Deserialize<Person>(json, options);
+    }
+
+    record Person(string Name, int? Age = null);
+    // </RequiredConstrParams>
+}