From c619ebef5150878039b7d1c4c81b895ecce38efb Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 3 Aug 2023 08:53:44 -0700 Subject: [PATCH 1/7] Updating Json package readme --- src/libraries/System.Text.Json/src/PACKAGE.md | 257 +++++++++++++++++- 1 file changed, 252 insertions(+), 5 deletions(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index 892946041791ca..c480f66e5164ab 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -1,11 +1,258 @@ ## About + + Provides high-performance and low-allocating types that serialize objects to JavaScript Object Notation (JSON) text and deserialize JSON text to objects, with UTF-8 support built-in. Also provides types to read and write JSON text encoded as UTF-8, and to create an in-memory document object model (DOM), that is read-only, for random access of the JSON elements within a structured view of the data. -The `System.Text.Json` library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use it in other target frameworks. +## How to Use + + +The System.Text.Json library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use it in other target frameworks. + +Serialization: +```csharp +using System; +using System.Text.Json; + +WeatherForecast forecast = new (DateTimeOffset.Now, 26.6f, "Sunny"); +var serialized = JsonSerializer.Serialize(forecast); + +Console.WriteLine(serialized); +// {"Date":"2023-08-02T16:01:20.9025406+00:00","TemperatureCelsius":26.6,"Summary":"Sunny"} + +var forecastDeserialized = JsonSerializer.Deserialize(serialized); +Console.WriteLine(forecast == forecastDeserialized); +// True + +public record WeatherForecast(DateTimeOffset Date, float TemperatureCelsius, string? Summary); +``` + +Serialization using the source generator: +```csharp +using System.Text.Json; +using System.Text.Json.Serialization; + +WeatherForecast forecast = new (DateTimeOffset.Now, 26.6f, "Sunny"); +var serialized = JsonSerializer.Serialize(forecast, SourceGenerationContext.Default.WeatherForecast); + +Console.WriteLine(serialized); +// {"Date":"2023-08-02T16:01:20.9025406+00:00","TemperatureCelsius":26.6,"Summary":"Sunny"} + +var forecastDeserialized = JsonSerializer.Deserialize(serialized, SourceGenerationContext.Default.WeatherForecast); +Console.WriteLine(forecast == forecastDeserialized); +// True + +public record WeatherForecast(DateTimeOffset Date, float TemperatureCelsius, string? Summary); + +[JsonSourceGenerationOptions(WriteIndented = true)] +[JsonSerializable(typeof(WeatherForecast))] +internal partial class SourceGenerationContext : JsonSerializerContext +{ +} +``` + +Using the JSON DOM: +```csharp + +using System; +using System.Text.Json; +using System.Text.Json.Nodes; + +string jsonString = +@"{ + ""Date"": ""2019-08-01T00:00:00"", + ""Temperature"": 25, + ""Summary"": ""Hot"", + ""DatesAvailable"": [ + ""2019-08-01T00:00:00"", + ""2019-08-02T00:00:00"" + ], + ""TemperatureRanges"": { + ""Cold"": { + ""High"": 20, + ""Low"": -10 + }, + ""Hot"": { + ""High"": 60, + ""Low"": 20 + } + } +} +"; + +JsonNode forecastNode = JsonNode.Parse(jsonString)!; + + +// Get value from a JsonNode. +JsonNode temperatureNode = forecastNode!["Temperature"]!; +Console.WriteLine($"Type={temperatureNode.GetType()}"); +Console.WriteLine($"JSON={temperatureNode.ToJsonString()}"); +//output: +//Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement] +//JSON = 25 + +// Get a typed value from a JsonNode. +int temperatureInt = (int)forecastNode!["Temperature"]!; +Console.WriteLine($"Value={temperatureInt}"); +//output: +//Value=25 + +// Get a typed value from a JsonNode by using GetValue. +temperatureInt = forecastNode!["Temperature"]!.GetValue(); +Console.WriteLine($"TemperatureInt={temperatureInt}"); +//output: +//Value=25 + +// Get a JSON object from a JsonNode. +JsonNode temperatureRanges = forecastNode!["TemperatureRanges"]!; +Console.WriteLine($"Type={temperatureRanges.GetType()}"); +Console.WriteLine($"JSON={temperatureRanges.ToJsonString()}"); +//output: +//Type = System.Text.Json.Nodes.JsonObject +//JSON = { "Cold":{ "High":20,"Low":-10},"Hot":{ "High":60,"Low":20} } + +// Get a JSON array from a JsonNode. +JsonNode datesAvailable = forecastNode!["DatesAvailable"]!; +Console.WriteLine($"Type={datesAvailable.GetType()}"); +Console.WriteLine($"JSON={datesAvailable.ToJsonString()}"); +//output: +//datesAvailable Type = System.Text.Json.Nodes.JsonArray +//datesAvailable JSON =["2019-08-01T00:00:00", "2019-08-02T00:00:00"] + +// Get an array element value from a JsonArray. +JsonNode firstDateAvailable = datesAvailable[0]!; +Console.WriteLine($"Type={firstDateAvailable.GetType()}"); +Console.WriteLine($"JSON={firstDateAvailable.ToJsonString()}"); +//output: +//Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement] +//JSON = "2019-08-01T00:00:00" + +// Get a typed value by chaining references. +int coldHighTemperature = (int)forecastNode["TemperatureRanges"]!["Cold"]!["High"]!; +Console.WriteLine($"TemperatureRanges.Cold.High={coldHighTemperature}"); +//output: +//TemperatureRanges.Cold.High = 20 + +// Parse a JSON array +var datesNode = JsonNode.Parse(@"[""2019-08-01T00:00:00"",""2019-08-02T00:00:00""]"); +JsonNode firstDate = datesNode![0]!.GetValue(); +Console.WriteLine($"firstDate={ firstDate}"); +//output: +//firstDate = "2019-08-01T00:00:00" +``` + +Using the reader/writer +```csharp +/* + SharpLab tools in Run mode: + • value.Inspect() + • Inspect.Heap(object) + • Inspect.Stack(value) + • Inspect.MemoryGraph(value1, value2, …) +*/ +using System; +using System.IO; +using System.Text; +using System.Text.Json; + +var writerOptions = new JsonWriterOptions +{ + Indented = true +}; + +using var stream = new MemoryStream(); +using var writer = new Utf8JsonWriter(stream, writerOptions); + +writer.WriteStartObject(); +writer.WriteString("date", DateTimeOffset.Parse("8/2/2023 9:00 AM")); +writer.WriteNumber("temp", 42); +writer.WriteEndObject(); +writer.Flush(); + +var jsonBytes = stream.ToArray(); +string json = Encoding.UTF8.GetString(jsonBytes); +Console.WriteLine(json); +// { +// "date": "2023-08-02T09:00:00+00:00" +// "temp": 42 +// } + +var readerOptions = new JsonReaderOptions +{ + AllowTrailingCommas = true, + CommentHandling = JsonCommentHandling.Skip +}; +var reader = new Utf8JsonReader(jsonBytes, readerOptions); + +while (reader.Read()) +{ + Console.Write(reader.TokenType); + + switch (reader.TokenType) + { + case JsonTokenType.PropertyName: + case JsonTokenType.String: + { + string? text = reader.GetString(); + Console.Write(" "); + Console.Write(text); + break; + } + + case JsonTokenType.Number: + { + int intValue = reader.GetInt32(); + Console.Write(" "); + Console.Write(intValue); + break; + } + + // Other token types elided for brevity + } + Console.WriteLine(); +} +// StartObject +// PropertyName date +// String 2023-08-02T09:00:00+00:00 +// PropertyName temp +// Number 42 +// EndObject +``` + +## Key Features + + + +TODO + +## Main Types + + + +The main types provided by this library are: + +* `System.Text.Json.JsonSerializer` +* `System.Text.Json.JsonDocument` +* `System.Text.Json.JsonElement` +* `System.Text.Json.Nodes.JsonNode` +* `System.Text.Json.Utf8JsonWriter` +* `System.Text.Json.Utf8JsonReader` + +## Addtional Documentation + +* [Conceptual documentation](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/overview) +* [API documentation](https://learn.microsoft.com/en-us/dotnet/api/system.text.json) + +## Related Packages + + + +* Lightweight data formats abstraction: [System.Memory.Data](https://www.nuget.org/packages/System.Memory.Data/) +* Serialization of HttpContent: [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json/) + + +## Feedback & Contributing -For more information, see the documentation: + -- [JSON serialization and deserialization in .NET](https://docs.microsoft.com/dotnet/standard/serialization/system-text-json-overview) -- [How to serialize and deserialize JSON in .NET](https://docs.microsoft.com/dotnet/standard/serialization/system-text-json-how-to) -- [System.Text.Json API reference](https://docs.microsoft.com/dotnet/api/system.text.json) +System.Text.Json is released as open source under the [MIT license](https://licenses.nuget.org/MIT). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/dotnet/runtime). From 8f3f8f90e0e751530a9757951305c5b51ca6675e Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 3 Aug 2023 12:32:11 -0700 Subject: [PATCH 2/7] Update src/libraries/System.Text.Json/src/PACKAGE.md Co-authored-by: Eirik Tsarpalis --- src/libraries/System.Text.Json/src/PACKAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index c480f66e5164ab..86d1a382296365 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -7,7 +7,7 @@ Provides high-performance and low-allocating types that serialize objects to Jav ## How to Use -The System.Text.Json library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use it in other target frameworks. +The System.Text.Json library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use the most recent version in older target frameworks. Serialization: ```csharp From 868dca168a82848c7c5fa7b272395398ac2a383a Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 3 Aug 2023 12:39:43 -0700 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Eirik Tsarpalis --- src/libraries/System.Text.Json/src/PACKAGE.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index 86d1a382296365..fb069dca38e828 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -84,7 +84,7 @@ JsonNode forecastNode = JsonNode.Parse(jsonString)!; // Get value from a JsonNode. -JsonNode temperatureNode = forecastNode!["Temperature"]!; +JsonNode temperatureNode = forecastNode["Temperature"]!; Console.WriteLine($"Type={temperatureNode.GetType()}"); Console.WriteLine($"JSON={temperatureNode.ToJsonString()}"); //output: @@ -92,19 +92,19 @@ Console.WriteLine($"JSON={temperatureNode.ToJsonString()}"); //JSON = 25 // Get a typed value from a JsonNode. -int temperatureInt = (int)forecastNode!["Temperature"]!; +int temperatureInt = (int)forecastNode["Temperature"]!; Console.WriteLine($"Value={temperatureInt}"); //output: //Value=25 // Get a typed value from a JsonNode by using GetValue. -temperatureInt = forecastNode!["Temperature"]!.GetValue(); +temperatureInt = forecastNode["Temperature"]!.GetValue(); Console.WriteLine($"TemperatureInt={temperatureInt}"); //output: //Value=25 // Get a JSON object from a JsonNode. -JsonNode temperatureRanges = forecastNode!["TemperatureRanges"]!; +JsonNode temperatureRanges = forecastNode["TemperatureRanges"]!; Console.WriteLine($"Type={temperatureRanges.GetType()}"); Console.WriteLine($"JSON={temperatureRanges.ToJsonString()}"); //output: @@ -112,7 +112,7 @@ Console.WriteLine($"JSON={temperatureRanges.ToJsonString()}"); //JSON = { "Cold":{ "High":20,"Low":-10},"Hot":{ "High":60,"Low":20} } // Get a JSON array from a JsonNode. -JsonNode datesAvailable = forecastNode!["DatesAvailable"]!; +JsonNode datesAvailable = forecastNode["DatesAvailable"]!; Console.WriteLine($"Type={datesAvailable.GetType()}"); Console.WriteLine($"JSON={datesAvailable.ToJsonString()}"); //output: @@ -134,14 +134,14 @@ Console.WriteLine($"TemperatureRanges.Cold.High={coldHighTemperature}"); //TemperatureRanges.Cold.High = 20 // Parse a JSON array -var datesNode = JsonNode.Parse(@"[""2019-08-01T00:00:00"",""2019-08-02T00:00:00""]"); -JsonNode firstDate = datesNode![0]!.GetValue(); +JsonNode datesNode = JsonNode.Parse(@"[""2019-08-01T00:00:00"",""2019-08-02T00:00:00""]")!; +JsonNode firstDate = datesNode[0]!.GetValue(); Console.WriteLine($"firstDate={ firstDate}"); //output: //firstDate = "2019-08-01T00:00:00" ``` -Using the reader/writer +Using the low-level JSON reader/writer types ```csharp /* SharpLab tools in Run mode: From 0238443ea90b5652bbb7040c32032ee6140b64b5 Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Thu, 3 Aug 2023 12:42:39 -0700 Subject: [PATCH 4/7] Remove sharplab comment --- src/libraries/System.Text.Json/src/PACKAGE.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index fb069dca38e828..147fecc98d1a7e 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -143,13 +143,6 @@ Console.WriteLine($"firstDate={ firstDate}"); Using the low-level JSON reader/writer types ```csharp -/* - SharpLab tools in Run mode: - • value.Inspect() - • Inspect.Heap(object) - • Inspect.Stack(value) - • Inspect.MemoryGraph(value1, value2, …) -*/ using System; using System.IO; using System.Text; From ef732285d819e73c5c3a897e739fb64670ce8234 Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Fri, 4 Aug 2023 17:36:37 +0100 Subject: [PATCH 5/7] Update PACKAGE.md --- src/libraries/System.Text.Json/src/PACKAGE.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index 147fecc98d1a7e..9a9973be4e5e14 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -4,6 +4,14 @@ Provides high-performance and low-allocating types that serialize objects to JavaScript Object Notation (JSON) text and deserialize JSON text to objects, with UTF-8 support built-in. Also provides types to read and write JSON text encoded as UTF-8, and to create an in-memory document object model (DOM), that is read-only, for random access of the JSON elements within a structured view of the data. +## Key Features + +* High-performance reader and writer types for UTF-8 encoded JSON. +* A fully-featured JSON serializer for .NET types using reflection or source generated contracts. +* A high-performance read-only JSON DOM (JsonDocument) and a mutable DOM that interoperates with the serializer (JsonNode). +* Built-in support for async serialization, including IAsyncEnumerable support. +* Fully customizable contract model for serializable types. + ## How to Use @@ -212,10 +220,6 @@ while (reader.Read()) // EndObject ``` -## Key Features - - - TODO ## Main Types @@ -224,12 +228,13 @@ TODO The main types provided by this library are: +* `System.Text.Json.Utf8JsonWriter` +* `System.Text.Json.Utf8JsonReader` * `System.Text.Json.JsonSerializer` +* `System.Text.Json.JsonConverter` * `System.Text.Json.JsonDocument` -* `System.Text.Json.JsonElement` * `System.Text.Json.Nodes.JsonNode` -* `System.Text.Json.Utf8JsonWriter` -* `System.Text.Json.Utf8JsonReader` +* `System.Text.Json.Serialization.Metadata.JsonTypeInfo` ## Addtional Documentation From 53993856f9bdadecd5fd8ea2c1a2ccd34597d8ce Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Fri, 4 Aug 2023 17:37:17 +0100 Subject: [PATCH 6/7] Update PACKAGE.md --- src/libraries/System.Text.Json/src/PACKAGE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index 9a9973be4e5e14..3e4de10d9848bc 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -6,6 +6,8 @@ Provides high-performance and low-allocating types that serialize objects to Jav ## Key Features + + * High-performance reader and writer types for UTF-8 encoded JSON. * A fully-featured JSON serializer for .NET types using reflection or source generated contracts. * A high-performance read-only JSON DOM (JsonDocument) and a mutable DOM that interoperates with the serializer (JsonNode). @@ -15,6 +17,7 @@ Provides high-performance and low-allocating types that serialize objects to Jav ## How to Use + The System.Text.Json library is built-in as part of the shared framework in .NET Runtime. The package can be installed when you need to use the most recent version in older target frameworks. Serialization: From ca35796c4003e0560b79bb812bbc6ce57e7c233c Mon Sep 17 00:00:00 2001 From: Eric StJohn Date: Mon, 7 Aug 2023 11:14:12 -0700 Subject: [PATCH 7/7] Remove TODO --- src/libraries/System.Text.Json/src/PACKAGE.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/libraries/System.Text.Json/src/PACKAGE.md b/src/libraries/System.Text.Json/src/PACKAGE.md index 3e4de10d9848bc..1bfcd1da44e258 100644 --- a/src/libraries/System.Text.Json/src/PACKAGE.md +++ b/src/libraries/System.Text.Json/src/PACKAGE.md @@ -223,8 +223,6 @@ while (reader.Read()) // EndObject ``` -TODO - ## Main Types