From be8d63a52f416716ef8d86fe6f7ac3251a139f3c Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 19 Oct 2022 14:40:05 -0700 Subject: [PATCH 1/4] Add section on Utf8JsonReader.CopyString --- .../system-text-json/converters-how-to.md | 2 +- .../use-dom-utf8jsonreader-utf8jsonwriter.md | 27 ++++++++++++++++--- 2 files changed, 24 insertions(+), 5 deletions(-) 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..13977ddbb6ec2 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); +``` + ### 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 . @@ -327,7 +347,6 @@ while (reader.Read()) } } ``` - ### Use ValueTextEquals for property name lookups Don't use to do byte-by-byte comparisons by calling for property name lookups. Call instead, because that method unescapes any characters that are escaped in the JSON. Here's an example that shows how to search for a property that is named "name": From 82900e4f49a58328729360e34095f6b13fd8b5f6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 19 Oct 2022 14:42:19 -0700 Subject: [PATCH 2/4] add line back --- .../system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md | 1 + 1 file changed, 1 insertion(+) 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 13977ddbb6ec2..177198542f0f8 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 @@ -347,6 +347,7 @@ while (reader.Read()) } } ``` + ### Use ValueTextEquals for property name lookups Don't use to do byte-by-byte comparisons by calling for property name lookups. Call instead, because that method unescapes any characters that are escaped in the JSON. Here's an example that shows how to search for a property that is named "name": From e125da87239c9c6a81b63d39ef46b434584b0749 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 19 Oct 2022 14:47:34 -0700 Subject: [PATCH 3/4] fix xrefs --- .../system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 177198542f0f8..f17248077a620 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 @@ -287,7 +287,7 @@ Here's a JSON sample that the preceding code can read. The resulting summary mes ### 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 . +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 From 5720b19e6f628f66532672d098486a31e43c190b Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 20 Oct 2022 09:21:13 -0700 Subject: [PATCH 4/4] Update docs/standard/serialization/system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md Co-authored-by: Eirik Tsarpalis --- .../system-text-json/use-dom-utf8jsonreader-utf8jsonwriter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 f17248077a620..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 @@ -300,7 +300,7 @@ ReadOnlySpan source = buffer.Slice(0, charsRead); // Handle the unescaped JSON string. ParseUnescapedString(source); -ArrayPool.Shared.Return(buffer); +ArrayPool.Shared.Return(buffer, clearArray: true); ``` ### Read from a stream using `Utf8JsonReader`