From: FyiurAmron Date: Mon, 7 Oct 2019 15:51:44 +0000 (+0200) Subject: Fix naming of System.Text.Json methods in docs (dotnet/corefx#41562) X-Git-Tag: submit/tizen/20210909.063632~11031^2~352 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f029c0920e36f963e45ebdbbf6b9b226c4359a8a;p=platform%2Fupstream%2Fdotnet%2Fruntime.git Fix naming of System.Text.Json methods in docs (dotnet/corefx#41562) Commit migrated from https://github.com/dotnet/corefx/commit/81dfdbcad0937707346cadc3968c0c67241c64f8 --- diff --git a/src/libraries/System.Text.Json/docs/SerializerProgrammingModel.md b/src/libraries/System.Text.Json/docs/SerializerProgrammingModel.md index b22fa6b..daa41ed 100644 --- a/src/libraries/System.Text.Json/docs/SerializerProgrammingModel.md +++ b/src/libraries/System.Text.Json/docs/SerializerProgrammingModel.md @@ -4,7 +4,7 @@ The APIs shown here reflection Preview 5. Design points: - Due to time constraints, and to gather feedback, the feature set is intended to a minimum viable product for 3.0. - - An expectation is that a significant percent of Json.NET consumers would be able to use this, especially for ASP.NET scenarios. However, with the 3.0 release being a minimum viable product, that percent is not known. However, the percent will never be 100%, and that is neither a goal nor a long-term goal, because Json.NET has [many features](https://www.newtonsoft.com/json/help/html/JsonNetVsDotNetSerializers.htm) and some are not target requirements. +- An expectation is that a significant percent of Json.NET consumers would be able to use this, especially for ASP.NET scenarios. However, with the 3.0 release being a minimum viable product, that percent is not known. However, the percent will never be 100%, and that is neither a goal nor a long-term goal, because Json.NET has [many features](https://www.newtonsoft.com/json/help/html/JsonNetVsDotNetSerializers.htm) and some are not target requirements. - Simple POCO object scenarios are targeted. These are typically used for DTO scenarios. - The API designed to be extensible for new features in subsequent releases and by the community. - Design-time attributes for defining the various options, but still support modifications at run-time. @@ -29,7 +29,7 @@ Using a simple POCO class: To deserialize a JSON string into a POCO instance: ```cs string json = ... - Person person = JsonSerializer.Parse(json); + Person person = JsonSerializer.Deserialize(json); ``` To serialize an object to a JSON string: @@ -43,26 +43,25 @@ Note there are also byte[]-based methods of these which are faster than using th ```cs namespace System.Text.Json.Serialization { - public static class JsonSerializer + public static partial class JsonSerializer { - public static object Parse(ReadOnlySpan utf8Json, Type returnType, JsonSerializerOptions options = null); - public static TValue Parse(ReadOnlySpan utf8Json, JsonSerializerOptions options = null); - - public static object Parse(string json, Type returnType, JsonSerializerOptions options = null); - public static TValue Parse(string json, JsonSerializerOptions options = null); - - public static ValueTask ReadAsync(Stream utf8Json, Type returnType, JsonSerializerOptions options = null, CancellationToken cancellationToken = default(CancellationToken)); - public static ValueTask ReadAsync(Stream utf8Json, JsonSerializerOptions options = null, CancellationToken cancellationToken = default(CancellationToken)); - - // Naming of `ToBytes` TBD based on API review; may want to expose a char8[] in addition to byte[]. - public static byte[] ToBytes(object value, Type type, JsonSerializerOptions options = null); - public static byte[] ToBytes(TValue value, JsonSerializerOptions options = null); - - public static string ToString(object value, Type type, JsonSerializerOptions options = null); - public static string ToString(TValue value, JsonSerializerOptions options = null); - - public static Task WriteAsync(object value, Type type, Stream utf8Json, JsonSerializerOptions options = null, CancellationToken cancellationToken = default(CancellationToken)); - public static Task WriteAsync(TValue value, Stream utf8Json, JsonSerializerOptions options = null, CancellationToken cancellationToken = default(CancellationToken)); + public static object Deserialize(System.ReadOnlySpan utf8Json, System.Type returnType, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static object Deserialize(string json, System.Type returnType, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static TValue Deserialize(System.ReadOnlySpan utf8Json, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static TValue Deserialize(string json, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static System.Threading.Tasks.ValueTask DeserializeAsync(System.IO.Stream utf8Json, System.Type returnType, System.Text.Json.JsonSerializerOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; } + public static System.Threading.Tasks.ValueTask DeserializeAsync(System.IO.Stream utf8Json, System.Text.Json.JsonSerializerOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; } + public static object Deserialize(ref System.Text.Json.Utf8JsonReader reader, System.Type returnType, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static TValue Deserialize(ref System.Text.Json.Utf8JsonReader reader, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + + public static string Serialize(object value, System.Type inputType, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static string Serialize(TValue value, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static byte[] SerializeToUtf8Bytes(object value, System.Type inputType, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static byte[] SerializeToUtf8Bytes(TValue value, System.Text.Json.JsonSerializerOptions options = null) { throw null; } + public static System.Threading.Tasks.Task SerializeAsync(System.IO.Stream utf8Json, object value, System.Type inputType, System.Text.Json.JsonSerializerOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; } + public static System.Threading.Tasks.Task SerializeAsync(System.IO.Stream utf8Json, TValue value, System.Text.Json.JsonSerializerOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; } + public static void Serialize(System.Text.Json.Utf8JsonWriter writer, object value, System.Type inputType, System.Text.Json.JsonSerializerOptions options = null) { } + public static void Serialize(System.Text.Json.Utf8JsonWriter writer, TValue value, System.Text.Json.JsonSerializerOptions options = null) { } } } ``` @@ -116,7 +115,7 @@ To specify camel-casing: options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; // Be sure to specify the options class on calls to the serializer: - string json = JsonSerializer.ToString(person, options); + string json = JsonSerializer.Serialize(person, options); ``` It is possible to author a new converter by deriving from `JsonNamingPolicy` and overriding `ConvertName`. @@ -191,8 +190,8 @@ Json.NET: JsonSerializer: ```cs Person person = ...; - string json = JsonSerializer.ToBytes(person); - person = JsonSerializer.Parse(json); + string json = JsonSerializer.Serialize(person); + person = JsonSerializer.Deserialize(json); ``` ## Simple scenario with run-time settings Json.NET: @@ -206,7 +205,7 @@ JsonSerializer: ```cs var options = new JsonSerializerOptions(); options.IgnoreNullValues = true; - string json = JsonSerializer.ToString(person, options); + string json = JsonSerializer.Serialize(person, options); ``` Note that Json.NET also has a `JsonSerializer` class with instance methods for advanced scenarios. See also Json.NET [code samples](https://www.newtonsoft.com/json/help/html/Samples.htm) and [documentation](https://www.newtonsoft.com/json/help/html/R_Project_Documentation.htm). @@ -220,11 +219,11 @@ An instance of this class and exposed objects will be immutable once (de)seriali ## Static typing \ polymorphic behavior The Read\Write methods specify statically (at compile time) the POCO type through `` which below is ``: ```cs - Person person = JsonSerializer.Parse(utf8); - JsonSerializer.ToBytes(person); + Person person = JsonSerializer.Deserialize(utf8); + JsonSerializer.SerializeToUtf8Bytes(person); // Due to generic inference, Write can be simplified as: - JsonSerializer.ToBytes(person); + JsonSerializer.SerializeToUtf8Bytes(person); ``` For Read, this means that if the `utf8` data has additional properties that originally came from a derived class (e.g. a Customer class that derived from Person), only a Person object is instantiated. This is fairly obvious, since there is no hint to say a Customer was originally serialized. @@ -235,7 +234,7 @@ Because serialization of an object tree in an opt-out model (all properties are However, static typing also limits polymorphic scenarios. This overload can be used with `GetType()` to address this: ```cs - JsonSerializer.ToBytes(person, person.GetType()); + JsonSerializer.SerializeToUtf8Bytes(person, person.GetType()); ``` In this case, if `person` is actually a Customer object, the Customer will be serialized. @@ -247,7 +246,7 @@ The design supports async methods that can stream with a buffer size around the Currently the async `await` calls on Stream and Pipe is based on a byte threshold determined by the current buffer size. -For the Stream-based async methods, the Stream's `ReadAsync()` \ `WriteAsync()` are awaited. There is no call to `FlushAsync()` - it is expected the consumer does this or uses a Stream or an adapter that can auto-flush. +For the Stream-based async methods, the Stream's `DeserializeAsync()` \ `SerializeAsync()` are awaited. There is no call to `FlushAsync()` - it is expected the consumer does this or uses a Stream or an adapter that can auto-flush. ## Performance The goal is to have a super fast (de)serializer given the feature set with minimal overhead on top of the reader and writer.