Merge pull request #43113 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

.openpublishing.redirection.standard.json

@@ -739,6 +739,11 @@
             "source_path_from_root": "/docs/standard/serialization/system-text-json-use-dom-utf8jsonreader-utf8jsonwriter.md",
             "redirect_url": "/dotnet/standard/serialization/system-text-json/use-dom"
         },
+        {
+            "source_path_from_root": "/docs/standard/serialization/system-text-json/json-schema-exporter.md",
+            "redirect_url": "/dotnet/standard/serialization/system-text-json/extract-schema",
+            "redirect_document_id": true
+        },
         {
             "source_path_from_root": "/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md",
             "redirect_url": "/dotnet/standard/serialization/system-text-json/use-dom",

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

@@ -493,33 +493,7 @@ If you want to serialize with the [default options that ASP.NET Core uses](../..
 
 JSON is frequently used to represent types in method signatures as part of remote procedure&ndash;calling schemes. It's used, for example, as part of OpenAPI specifications, or as part of tool calling with AI services like those from OpenAI. Developers can serialize and deserialize .NET types as JSON using <xref:System.Text.Json>. But they also need to be able to get a JSON schema that describes the shape of the .NET type (that is, describes the shape of what would be serialized and what can be deserialized). <xref:System.Text.Json> now provides the <xref:System.Text.Json.Schema.JsonSchemaExporter> type, which supports generating a JSON schema that represents a .NET type.
 
-The following code generates a JSON schema from a type.
-
-:::code language="csharp" source="../snippets/dotnet-9/csharp/Serialization.cs" id="Schema":::
-
-The type is defined as follows:
-
-:::code language="csharp" source="../snippets/dotnet-9/csharp/Serialization.cs" id="Book":::
-
-The generated schema is:
-
-```json
-{
-    "type": ["object", "null"],
-    "properties": {
-        "Title": {
-            "type": "string"
-        },
-        "Author": {
-            "type": ["string", "null"]
-        },
-        "PublishYear": {
-            "type": "integer"
-        }
-    },
-    "required": ["Title"]
-}
-```
+For more information, see [JSON schema exporter](../../../standard/serialization/system-text-json/extract-schema.md).
 
 ### Respect nullable annotations
 
@@ -588,50 +562,9 @@ enum MyEnum
 
 ### 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:
-
-```csharp
-JsonReaderOptions options = new() { AllowMultipleValues = true };
-Utf8JsonReader reader = new("null {} 1 \r\n [1,2,3]"u8, options);
-
-reader.Read();
-Console.WriteLine(reader.TokenType); // Null
-
-reader.Read();
-Console.WriteLine(reader.TokenType); // StartObject
-reader.Skip();
-
-reader.Read();
-Console.WriteLine(reader.TokenType); // Number
+<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.
 
-reader.Read();
-Console.WriteLine(reader.TokenType); // StartArray
-reader.Skip();
-
-Console.WriteLine(reader.Read()); // False
-```
-
-This flag also makes it possible to read JSON from payloads that might contain trailing data that's invalid JSON:
-
-```csharp
-Utf8JsonReader reader = new("[1,2,3]    <NotJson/>"u8, new() { AllowMultipleValues = true });
-
-reader.Read();
-reader.Skip(); // Success
-reader.Read(); // throws JsonReaderException
-```
-
-When it comes to streaming deserialization, a new <xref:System.Text.Json.JsonSerializer.DeserializeAsyncEnumerable%60%601(System.IO.Stream,System.Boolean,System.Text.Json.JsonSerializerOptions,System.Threading.CancellationToken)?displayProperty=nameWithType> overload makes streaming multiple top-level values possible. By default, the method attempts to stream elements that are contained in a top-level JSON array. You can toggle this behavior using the new `topLevelValues` flag:
-
-```csharp
-ReadOnlySpan<byte> utf8Json = """[0] [0,1] [0,1,1] [0,1,1,2] [0,1,1,2,3]"""u8;
-using var stream = new MemoryStream(utf8Json.ToArray());
-
-await foreach (int[] item in JsonSerializer.DeserializeAsyncEnumerable<int[]>(stream, topLevelValues: true))
-{
-    Console.WriteLine(item.Length);
-}
-```
+For more information, see [Read multiple JSON documents](../../../standard/serialization/system-text-json/use-utf8jsonreader.md#read-multiple-json-documents).
 
 ## Spans
 

docs/csharp/whats-new/csharp-13.md

@@ -110,7 +110,7 @@ In the same fashion, C# 13 allows `unsafe` contexts in iterator methods. However
 
 Before C# 13, `ref struct` types couldn't be declared as the type argument for a generic type or method. Now, generic type declarations can add an anti-constraint, `allows ref struct`. This anti-constraint declares that the type argument supplied for that type parameter can be a `ref struct` type. The compiler enforces ref safety rules on all instances of that type parameter.
 
-For example, you may declare an interface like the following code:
+For example, you may declare a generic type like the following code:
 
 ```csharp
 public class C<T> where T : allows ref struct

docs/fundamentals/toc.yml

@@ -786,7 +786,7 @@ items:
                   - name: Customize contracts
                     href: ../standard/serialization/system-text-json/custom-contracts.md
                   - name: Extract JSON schema
-                    href: ../standard/serialization/system-text-json/json-schema-exporter.md
+                    href: ../standard/serialization/system-text-json/extract-schema.md
           - name: XML and SOAP serialization
             items:
               - name: Overview

docs/standard/frameworks.md

@@ -104,7 +104,7 @@ Use these guidelines to determine which TFM to use in your app:
 
 You can also specify an optional OS version at the end of an OS-specific TFM, for example, `net6.0-ios15.0`. The version indicates which APIs are available to your app or library. It doesn't control the OS version that your app or library supports at run time. It's used to select the reference assemblies that your project compiles against, and to select assets from NuGet packages. Think of this version as the "platform version" or "OS API version" to disambiguate it from the run-time OS version.
 
-When an OS-specific TFM doesn't specify the platform version explicitly, it has an implied value that can be inferred from the base TFM and platform name. For example, the default platform value for iOS in .NET 6 is `15.0`, which means that `net6.0-ios` is shorthand for the canonical `net6.0-ios15.0` TFM. The implied platform version for a newer base TFM may be higher, for example, a future `net8.0-ios` TFM could map to `net8.0-ios16.0`. The shorthand form is intended for use in project files only, and is expanded to the canonical form by the .NET SDK's MSBuild targets before being passed to other tools, such as NuGet.
+When an OS-specific TFM doesn't specify the platform version explicitly, it has an implied value that can be inferred from the base TFM and platform name. For example, the default platform value for Android in .NET 6 is `31.0`, which means that `net6.0-android` is shorthand for the canonical `net6.0-android31.0` TFM. The implied platform version for a newer base TFM may be higher, for example, a future `net8.0-android` TFM could map to `net8.0-android34.0`. The shorthand form is intended for use in project files only, and is expanded to the canonical form by the .NET SDK's MSBuild targets before being passed to other tools, such as NuGet.
 
 The following table shows the default target platform values (TPV) for each .NET release.
 
@@ -114,7 +114,18 @@ The following table shows the default target platform values (TPV) for each .NET
 | .NET 7       |    33.0 | 16.1 |         16.1 | 13.0  | 16.1 |   7.0 |     7.0 |
 | .NET 8       |    34.0 | 17.2 |         17.2 | 14.2  | 17.1 |   8.0 |     7.0 |
 
-The .NET SDK is designed to be able to support newly released APIs for an individual platform without a new version of the base TFM. This enables you to access platform-specific functionality without waiting for a major release of .NET. You can gain access to these newly released APIs by incrementing the platform version in the TFM. For example, if the iOS platform added iOS 15.1 APIs in a .NET 6.0.x SDK update, you could access them by using the TFM `net6.0-ios15.1`.
+> [!NOTE]
+> On Apple platforms (iOS, macOS, tvOS, and Mac Catalyst) in .NET 8 and earlier,
+> the default TPV is the latest supported version in the currently installed workload.
+> That means that updating the iOS workload in .NET 8, for example, might result in a higher default
+> TPV, if support for a new version of iOS has been added in that workload. In the preceding table,
+> the default TPV is the one in the initial release for the stated .NET version.
+>
+> Starting in .NET 9, this special behavior only applies to executable projects.
+> The default TPV for library projects now stays the same for the entirety of
+> a major .NET release, like all other platforms.
+
+The .NET SDK is designed to be able to support newly released APIs for an individual platform without a new version of the base TFM. This enables you to access platform-specific functionality without waiting for a major release of .NET. You can gain access to these newly released APIs by incrementing the platform version in the TFM. For example, if the Android platform added API level 32 APIs in a .NET 6.0.x SDK update, you could access them by using the TFM `net6.0-android32.0`.
 
 #### Precedence
 

docs/standard/serialization/system-text-json/json-schema-exporter.md renamed to docs/standard/serialization/system-text-json/extract-schema.md

@@ -8,7 +8,7 @@ dev_langs:
 
 # JSON schema exporter
 
-The new <xref:System.Text.Json.Schema.JsonSchemaExporter> class lets you extract [JSON schema](https://json-schema.org/) documents from .NET types using either a <xref:System.Text.Json.JsonSerializerOptions> or <xref:System.Text.Json.Serialization.Metadata.JsonTypeInfo> instance. The resultant schema provides a specification of the JSON serialization contract for the type.
+The <xref:System.Text.Json.Schema.JsonSchemaExporter> class, introduced in .NET 9, lets you extract [JSON schema](https://json-schema.org/) documents from .NET types using either a <xref:System.Text.Json.JsonSerializerOptions> or <xref:System.Text.Json.Serialization.Metadata.JsonTypeInfo> instance. The resultant schema provides a specification of the JSON serialization contract for the .NET type. The schema describes the shape of what would be serialized and what can be deserialized.
 
 The following code snippet shows an example.
 

docs/standard/serialization/system-text-json/handle-overflow.md

@@ -14,7 +14,7 @@ helpviewer_keywords:
 ms.topic: how-to
 ---
 
-# How to handle overflow JSON or use JsonElement or JsonNode in System.Text.Json
+# How to handle overflow JSON or use JsonElement or JsonNode
 
 This article shows how to handle overflow JSON with the <xref:System.Text.Json> namespace. It also shows how to deserialize into <xref:System.Text.Json.JsonElement> or <xref:System.Text.Json.Nodes.JsonNode>, as an alternative for other scenarios where the target type might not perfectly match all of the JSON being deserialized.
 
@@ -86,7 +86,7 @@ The following example shows a round trip from JSON to a deserialized object and
 
 ## Deserialize into JsonElement or JsonNode
 
-If you just want to be flexible about what JSON is acceptable for a particular property, an alternative is to deserialize into <xref:System.Text.Json.JsonElement> or <xref:System.Text.Json.Nodes.JsonNode>. Any valid JSON property can be deserialized into `JsonElement` or `JsonNode`. Choose `JsonElement` to create an immutable object or `JsonNode` to create a mutable object.
+If you just want to be flexible about what JSON is acceptable for a particular property, an alternative is to deserialize into <xref:System.Text.Json.JsonElement> or <xref:System.Text.Json.Nodes.JsonNode>. Any valid JSON property can be deserialized into `JsonElement` or `JsonNode`. Choose `JsonElement` to create an *immutable* object or `JsonNode` to create a *mutable* object.
 
 The following example shows a round trip from JSON and back to JSON for a class that includes properties of type `JsonElement` and `JsonNode`.
 

docs/standard/serialization/system-text-json/how-to.md

@@ -33,7 +33,7 @@ The following example creates JSON as a string:
 :::code language="csharp" source="snippets/how-to/csharp/SerializeBasic.cs" id="all" highlight="23":::
 :::code language="vb" source="snippets/how-to/vb/RoundtripToString.vb" id="Serialize":::
 
-The JSON output is minified (whitespace, indentation, and new-line characters are removed) by default.
+The JSON output is *minified* (whitespace, indentation, and new-line characters are removed) by default.
 
 The following example uses synchronous code to create a JSON file:
 
@@ -104,6 +104,8 @@ To pretty-print the JSON output, set <xref:System.Text.Json.JsonSerializerOption
 :::code language="csharp" source="snippets/how-to/csharp/SerializeWriteIndented.cs" highlight="24":::
 :::code language="vb" source="snippets/how-to/vb/RoundtripToString.vb" id="SerializePrettyPrint":::
 
+Starting in .NET 9, you can also customize the indent character and size using <xref:System.Text.Json.JsonSerializerOptions.IndentCharacter> and <xref:System.Text.Json.JsonSerializerOptions.IndentSize>.
+
 > [!TIP]
 > If you use `JsonSerializerOptions` repeatedly with the same options, don't create a new `JsonSerializerOptions` instance each time you use it. Reuse the same instance for every call. For more information, see [Reuse JsonSerializerOptions instances](configure-options.md#reuse-jsonserializeroptions-instances).
 

docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md

@@ -782,8 +782,8 @@ If you need to continue to use `Newtonsoft.Json` for certain target frameworks,
 
 Starting in .NET 9, you can customize the indentation character and size for <xref:System.Text.Json.Utf8JsonWriter> using options exposed by the <xref:System.Text.Json.JsonWriterOptions> struct:
 
-* `JsonWriterOptions.IndentCharacter` <!-- <xref:System.Text.Json.JsonWriterOptions.IndentCharacter> -->
-* `JsonWriterOptions.IndentSize` <!-- <xref:System.Text.Json.JsonWriterOptions.IndentSize> -->
+* <xref:System.Text.Json.JsonWriterOptions.IndentCharacter?displayProperty=nameWithType>
+* <xref:System.Text.Json.JsonWriterOptions.IndentSize?displayProperty=nameWithType>
 
 ::: zone-end
 

docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/ImmutableTypes.cs

@@ -8,7 +8,7 @@ public struct Forecast
         public DateTime Date { get; }
         public int TemperatureC { get; }
         public string Summary { get; }
- 
+
         [JsonConstructor]
         public Forecast(DateTime date, int temperatureC, string summary) =>
             (Date, TemperatureC, Summary) = (date, temperatureC, summary);
@@ -27,7 +27,7 @@ public static void Main()
                 """;
             Console.WriteLine($"Input JSON: {json}");
 
-            var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
+            var options = JsonSerializerOptions.Web;
 
             Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options);