Document mutable DOM #24963
Merged
Document mutable DOM #24963
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
CamSoper
approved these changes
Jul 8, 2021
layomia
reviewed
Sep 21, 2021
| The following sections show how to use these APIs for reading and writing JSON. | ||
| * A [JSON Document Object Model (DOM)](#json-dom-choices) for random access to data in a JSON payload. | ||
| * The [`Utf8JsonWriter`](#use-utf8jsonwriter) type for building custom serializers. | ||
| * The [`Utf8JsonReader`](#use-utf8jsonreader) type for building custom parsers and deserializers. | ||
|
|
||
| > [!NOTE] | ||
| > The article about migrating from Newtonsoft has more information about these APIs. See the following sections in that article: |
There was a problem hiding this comment.
nit: I read this to mean the referenced article has more detailed info about these APIs. Seems weird given that the current one is dedicated to these APIs.
There was a problem hiding this comment.
I'm moving the content that isn't specific to migration from Newtonsoft from the Newtonsoft article to this article, which eliminates the need for this note.
| ## Use JsonDocument for access to data | ||
| ## JSON DOM choices | ||
|
|
||
| Working with a DOM is an alternative to deserialization: |
There was a problem hiding this comment.
nit: to deserialization *with JsonSerializer
| :::zone pivot="dotnet-6-0,dotnet-5-0,dotnet-core-3-1" | ||
| <xref:System.Text.Json.JsonDocument> provides the ability to build a read-only Document Object Model (DOM) by using `Utf8JsonReader`. The DOM provides random access to data in a JSON payload. The JSON elements that compose the payload can be accessed via the <xref:System.Text.Json.JsonElement> type. The `JsonElement` type provides array and object enumerators along with APIs to convert JSON text to common .NET types. `JsonDocument` exposes a <xref:System.Text.Json.JsonDocument.RootElement> property. | ||
| :::zone-end | ||
| # How to use a DOM, Utf8JsonReader, and Utf8JsonWriter in System.Text.Json |
There was a problem hiding this comment.
nit, since this is the first occurrence: How to use a JSON document (DOM)
| @@ -738,7 +738,7 @@ Searches for JSON tokens using `JObject` or `JArray` from `Newtonsoft.Json` tend | |||
| * Use the built-in enumerators (<xref:System.Text.Json.JsonElement.EnumerateArray%2A> and <xref:System.Text.Json.JsonElement.EnumerateObject%2A>) rather than doing your own indexing or loops. | |||
| * Don't do a sequential search on the whole `JsonDocument` through every property by using `RootElement`. Instead, search on nested JSON objects based on the known structure of the JSON data. For example, if you're looking for a `Grade` property in `Student` objects, loop through the `Student` objects and get the value of `Grade` for each, rather than searching through all `JsonElement` objects looking for `Grade` properties. Doing the latter will result in unnecessary passes over the same data. | |||
|
|
|||
| For a code example, see [Use JsonDocument for access to data](system-text-json-use-dom-utf8jsonreader-utf8jsonwriter.md#use-jsondocument-for-access-to-data). | |||
| For a code example, see [Use JsonDocument](system-text-json-use-dom-utf8jsonreader-utf8jsonwriter.md#use-jsondocument). | |||
There was a problem hiding this comment.
Should this section also talk about mutable DOM types? Seems like an omission
| }; | ||
|
|
||
| // Add an object. | ||
| forecastObject["TemperatureRanges"].AsObject().Add( |
There was a problem hiding this comment.
Can this be
forecastObject["TemperatureRanges"]["Hot"] = ...;| { | ||
| public class Program | ||
| { | ||
| public static DateTime[] DatesAvailable { get; set; } |
There was a problem hiding this comment.
This property is not used.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #24641
Fixes #24252