diff --git a/docs/standard/serialization/system-text-json/converters-how-to.md b/docs/standard/serialization/system-text-json/converters-how-to.md index 7ed23fae251c4..3e2abf10f4a8b 100644 --- a/docs/standard/serialization/system-text-json/converters-how-to.md +++ b/docs/standard/serialization/system-text-json/converters-how-to.md @@ -96,7 +96,7 @@ The preceding code is the same as what is shown in the [Support Dictionary with The following steps explain how to create a converter by following the basic pattern: * Create a class that derives from where `T` is the type to be serialized and deserialized. -* Override the `Read` method to deserialize the incoming JSON and convert it to type `T`. Use the that is passed to the method to read the JSON. You don't have to worry about handling partial data, as the serializer passes all the data for the current JSON scope. So it isn't necessary to call or or to validate that returns `true`. +* Override the `Read` method to deserialize the incoming JSON and convert it to type `T`. Use the that's passed to the method to read the JSON. You don't have to worry about handling partial data, as the serializer passes all the data for the current JSON scope. So it isn't necessary to call or or to validate that returns `true`. * Override the `Write` method to serialize the incoming object of type `T`. Use the that is passed to the method to write the JSON. * Override the `CanConvert` method only if necessary. The default implementation returns `true` when the type to convert is of type `T`. Therefore, converters that support only type `T` don't need to override this method. For an example of a converter that does need to override this method, see the [polymorphic deserialization](#support-polymorphic-deserialization) section later in this article. diff --git a/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md b/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md index f5461bc399fc9..81f7d8f63c2ea 100644 --- a/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md +++ b/docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md @@ -249,7 +249,9 @@ To write `Timespan`, `Uri`, or `char` values, format them as strings (by calling ## Use `Utf8JsonReader` - is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a `ReadOnlySpan` or `ReadOnlySequence`. The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. The method uses `Utf8JsonReader` under the covers. The `Utf8JsonReader` can't be used directly from Visual Basic code. For more information, see [Visual Basic support](visual-basic-support.md). + is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a `ReadOnlySpan` or `ReadOnlySequence`. The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. The method uses `Utf8JsonReader` under the covers. + +> `Utf8JsonReader` can't be used directly from Visual Basic code. For more information, see [Visual Basic support](visual-basic-support.md). The following example shows how to use the class: @@ -260,7 +262,7 @@ The preceding code assumes that the `jsonUtf8` variable is a byte array that con ### Filter data using `Utf8JsonReader` -The following example shows how to synchronously read a file, and search for a value. +The following example shows how to synchronously read a file and search for a value. :::code language="csharp" source="snippets/system-text-json-how-to/csharp/Utf8ReaderFromFile.cs"::: :::code language="vb" source="snippets/system-text-json-how-to/vb/Utf8ReaderFromFile.vb"::: @@ -271,7 +273,7 @@ The preceding code: * Assumes the JSON contains an array of objects and each object may contain a "name" property of type string. * Counts objects and "name" property values that end with "University". -* Assumes the file is encoded as UTF-16 and transcodes it into UTF-8. A file encoded as UTF-8 can be read directly into a `ReadOnlySpan`, by using the following code: +* Assumes the file is encoded as UTF-16 and transcodes it into UTF-8. A file encoded as UTF-8 can be read directly into a `ReadOnlySpan` by using the following code: ```csharp ReadOnlySpan jsonReadOnlySpan = File.ReadAllBytes(fileName); @@ -283,6 +285,24 @@ Here's a JSON sample that the preceding code can read. The resulting summary mes :::code language="json" source="snippets/system-text-json-how-to/csharp/Universities.json"::: +### Consume decoded JSON strings + +Starting in .NET 7, you can use the method instead of to consume a decoded JSON string. Unlike , which always allocates a new string, lets you copy the unescaped string to a buffer that you own. The following code snippet shows an example of consuming a UTF-16 string using . + +```csharp +int valueLength = reader.HasReadOnlySequence + ? checked((int)ValueSequence.Length) + : ValueSpan.Length; + +char[] buffer = ArrayPool.Shared.Rent(valueLength); +int charsRead = reader.CopyString(buffer); +ReadOnlySpan source = buffer.Slice(0, charsRead); + +// Handle the unescaped JSON string. +ParseUnescapedString(source); +ArrayPool.Shared.Return(buffer, clearArray: true); +``` + ### Read from a stream using `Utf8JsonReader` When reading a large file (a gigabyte or more in size, for example), you might want to avoid having to load the entire file into memory at once. For this scenario, you can use a .