New article - Migrate from Newtonsoft.Json

docs/standard/serialization/system-text-json-converters-how-to.md

@@ -2,7 +2,7 @@
 title: "How to write custom converters for JSON serialization - .NET"
 author: tdykstra
 ms.author: tdykstra
-ms.date: "10/16/2019"
+ms.date: "12/20/2019"
 helpviewer_keywords: 
   - "JSON serialization"
   - "serializing objects"
@@ -11,7 +11,7 @@ helpviewer_keywords:
   - "converters"
 ---
 
-# How to write custom converters for JSON serialization in .NET
+# How to write custom converters for JSON serialization (marshalling) in .NET
 
 This article shows how to create custom converters for the JSON serialization classes that are provided in the <xref:System.Text.Json> namespace. For an introduction to `System.Text.Json`, see [How to serialize and deserialize JSON in .NET](system-text-json-how-to.md).
 
@@ -20,7 +20,7 @@ A *converter* is a class that converts an object or a value to and from JSON. Th
 * To override the default behavior of a built-in converter. For example, you might want `DateTime` values to be represented by mm/dd/yyyy format instead of the default  ISO 8601-1:2019 format.
 * To support a custom value type. For example, a `PhoneNumber` struct.
 
-You can also write custom converters to extend `System.Text.Json` with functionality not included in the current release. The following scenarios are covered later in this article:
+You can also write custom converters to customize or extend `System.Text.Json` with functionality not included in the current release. The following scenarios are covered later in this article:
 
 * [Deserialize inferred types to Object properties](#deserialize-inferred-types-to-object-properties).
 * [Support Dictionary with non-string key](#support-dictionary-with-non-string-key).
@@ -65,9 +65,9 @@ The following steps explain how to create a converter by following the basic pat
 * Create a class that derives from <xref:System.Text.Json.Serialization.JsonConverter%601> 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 <xref:System.Text.Json.Utf8JsonReader> that is passed to the method to read the JSON.
 * Override the `Write` method to serialize the incoming object of type `T`. Use the <xref:System.Text.Json.Utf8JsonWriter> 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 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.
+* 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.
 
-You can refer to the [built-in converters source code](https://github.com/dotnet/corefx/tree/master/src/System.Text.Json/src/System/Text/Json/Serialization/Converters/) as reference implementations for writing custom converters.
+You can refer to the [built-in converters source code](https://github.com/dotnet/runtime/tree/f77914d4c9045a01b3a91b63c28805f24850c274/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/) as reference implementations for writing custom converters.
 
 ## Steps to follow the factory pattern
 
@@ -183,7 +183,8 @@ Type inference can be inaccurate. If the deserializer parses a JSON number that
 For scenarios that require type inference, the following code shows a custom converter for `Object` properties. The code converts:
 
 * `true` and `false` to `Boolean`
-* Numbers to `long` or `double`
+* Numbers without a decimal to `long`
+* Numbers with a decimal to `double`
 * Dates to `DateTime`
 * Strings to `string`
 * Everything else to `JsonElement`
@@ -242,7 +243,7 @@ The JSON output from serialization looks like the following example:
 }
 ```
 
-The [unit tests folder](https://github.com/dotnet/corefx/blob/master/src/System.Text.Json/tests/Serialization/) in the `System.Text.Json.Serialization` namespace has more examples of custom converters that handle non-string-key dictionaries.
+The [unit tests folder](https://github.com/dotnet/corefx/blob/f77914d4c9045a01b3a91b63c28805f24850c274/src/System.Text.Json/tests/Serialization/) in the `System.Text.Json.Serialization` namespace has more examples of custom converters that handle non-string-key dictionaries.
 
 ### Support polymorphic deserialization
 
@@ -279,22 +280,25 @@ The converter can deserialize JSON that was created by using the same converter
 
 ## Other custom converter samples
 
-The [unit tests folder](https://github.com/dotnet/corefx/blob/master/src/System.Text.Json/tests/Serialization/) in the `System.Text.Json.Serialization` source code includes other custom converter samples, such as:
+The [Migrate from Newtonsoft.Json to System.Text.Json](system-text-json-migrate-from-newtonsoft-how-to.md) article contains additional samples of custom converters.
+
+The [unit tests folder](https://github.com/dotnet/runtime/blob/f77914d4c9045a01b3a91b63c28805f24850c274/src/libraries/System.Text.Json/tests/Serialization/) in the `System.Text.Json.Serialization` source code includes other custom converter samples, such as:
 
 * `Int32` converter that converts null to 0 on deserialize
 * `Int32` converter that allows both string and number values on deserialize
 * `Enum` converter
 * `List<T>` converter that accepts external data
 * `Long[]` converter that works with a comma-delimited list of numbers 
 
+If you need to make a converter that modifies the behavior of an existing built-in converter, you can get [the source code of the existing converter](https://github.com/dotnet/runtime/tree/f77914d4c9045a01b3a91b63c28805f24850c274/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters) to serve as a starting point for customization.
+
 ## Additional resources
 
+* [Source code for built-in converters](https://github.com/dotnet/runtime/tree/f77914d4c9045a01b3a91b63c28805f24850c274/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/)
+* [DateTime and DateTimeOffset support in System.Text.Json](../datetime/system-text-json-support.md)
 * [System.Text.Json overview](system-text-json-overview.md)
-* [System.Text.Json API reference](xref:System.Text.Json)
 * [How to use System.Text.Json](system-text-json-how-to.md)
-* [Source code for built-in converters](https://github.com/dotnet/corefx/tree/master/src/System.Text.Json/src/System/Text/Json/Serialization/Converters/)
-* GitHub issues related to custom converters for `System.Text.Json`
-  * [36639 Introducing custom converters](https://github.com/dotnet/corefx/issues/36639)
-  * [38713 About deserializing to Object](https://github.com/dotnet/corefx/issues/38713)
-  * [40120 About non-string-key dictionaries](https://github.com/dotnet/corefx/issues/40120)
-  * [37787 About polymorphic deserialization](https://github.com/dotnet/corefx/issues/37787)
+* [How to migrate from Newtonsoft.Json](system-text-json-migrate-from-newtonsoft-how-to.md)
+* [System.Text.Json API reference](xref:System.Text.Json)
+* [System.Text.Json.Serialization API reference](xref:System.Text.Json.Serialization)
+<!-- * [System.Text.Json roadmap](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Text.Json/roadmap/README.md)-->

docs/standard/serialization/system-text-json-how-to.md

@@ -2,15 +2,15 @@
 title: "How to serialize and deserialize JSON using C# - .NET"
 author: tdykstra
 ms.author: tdykstra
-ms.date: "09/16/2019"
+ms.date: "12/20/2019"
 helpviewer_keywords: 
   - "JSON serialization"
   - "serializing objects"
   - "serialization"
   - "objects, serializing"
 ---
 
-# How to serialize and deserialize JSON in .NET
+# How to serialize and deserialize (marshal and unmarshal) JSON in .NET
 
 This article shows how to use the <xref:System.Text.Json> namespace to serialize and deserialize to and from JavaScript Object Notation (JSON).
 
@@ -106,7 +106,7 @@ Serializing to UTF-8 is about 5-10% faster than using the string-based methods.
 * The [default encoder](xref:System.Text.Encodings.Web.JavaScriptEncoder.Default) escapes non-ASCII characters, HTML-sensitive characters within the ASCII-range, and characters that must be escaped according to [the RFC 8259 JSON spec](https://tools.ietf.org/html/rfc8259#section-7).
 * By default, JSON is minified. You can [pretty-print the JSON](#serialize-to-formatted-json).
 * By default, casing of JSON names matches the .NET names. You can [customize JSON name casing](#customize-json-names-and-values).
-* Circular references are detected and exceptions thrown. For more information, see [issue 38579 on circular references](https://github.com/dotnet/corefx/issues/38579) in the dotnet/corefx repository on GitHub.
+* Circular references are detected and exceptions thrown.
 * Currently, fields are excluded.
 
 Supported types include:
@@ -115,7 +115,7 @@ Supported types include:
 * User-defined [Plain Old CLR Objects (POCOs)](https://stackoverflow.com/questions/250001/poco-definition).
 * One-dimensional and jagged arrays (`ArrayName[][]`).
 * `Dictionary<string,TValue>` where `TValue` is `object`, `JsonElement`, or a POCO.
-* Collections from the following namespaces. For more information, see the [issue on collection support](https://github.com/dotnet/corefx/issues/36643) in the dotnet/corefx repository on GitHub.
+* Collections from the following namespaces.
   * <xref:System.Collections>
   * <xref:System.Collections.Generic>
   * <xref:System.Collections.Immutable>
@@ -151,13 +151,13 @@ To deserialize from UTF-8, call a <xref:System.Text.Json.JsonSerializer.Deserial
 * By default, property name matching is case-sensitive. You can [specify case-insensitivity](#case-insensitive-property-matching).
 * If the JSON contains a value for a read-only property, the value is ignored and no exception is thrown.
 * Deserialization to reference types without a parameterless constructor isn't supported.
-* Deserialization to immutable objects or read-only properties isn't supported. For more information, see GitHub [issue 38569 on immutable object support](https://github.com/dotnet/corefx/issues/38569) and [issue 38163 on read-only property support](https://github.com/dotnet/corefx/issues/38163) in the dotnet/corefx repository on GitHub.
+* Deserialization to immutable objects or read-only properties isn't supported.
 * By default, enums are supported as numbers. You can [serialize enum names as strings](#enums-as-strings).
 * Fields aren't supported.
 * By default, comments or trailing commas in the JSON throw exceptions. You can [allow comments and trailing commas](#allow-comments-and-trailing-commas).
 * The [default maximum depth](xref:System.Text.Json.JsonReaderOptions.MaxDepth) is 64.
 
-You can [implement custom converters](system-text-json-converters-how-to.md) to provide functionality that isn't supported by the built-in converters.
+You can [implement custom converters](system-text-json-converters-how-to.md) to provide functionality that isn't supported by the built-in converters. For more information, see [How to migrate from Newtonsoft.Json to System.Text.Json](system-text-json-migrate-from-newtonsoft-how-to.md).
 
 ## Serialize to formatted JSON
 
@@ -498,7 +498,7 @@ In the preceding example scenario, both approaches cause the `WindSpeed` propert
 }
 ```
 
-For information about polymorphic deserialization, see [Support polymorphic deserialization](system-text-json-converters-how-to.md#support-polymorphic-deserialization).
+This section shows how to do **serialization**. For information about polymorphic **deserialization**, see [How to migrate from Newtonsoft.Json to System.Text.Json](system-text-json-migrate-from-newtonsoft-how-to.md#polymorphic-deserialization).
 
 ## Allow comments and trailing commas
 
@@ -623,7 +623,7 @@ To change this behavior, set <xref:System.Text.Json.JsonSerializerOptions.Ignore
 
 With this option, the `Summary` property of the `WeatherForecastWithDefault` object is the default value "No summary" after deserialization.
 
-Null values in the JSON are ignored only if they are valid. Null values for non-nullable value types cause exceptions. For more information, see [issue 40922 on non-nullable value types](https://github.com/dotnet/corefx/issues/40922) in the dotnet/corefx repository on GitHub.
+Null values in the JSON are ignored only if they are valid. Null values for non-nullable value types cause exceptions.
 
 ## Utf8JsonReader, Utf8JsonWriter, and JsonDocument
 
@@ -712,7 +712,8 @@ Here's a JSON sample that the preceding code can read. The resulting summary mes
 ## Additional resources
 
 * [System.Text.Json overview](system-text-json-overview.md)
-* [System.Text.Json API reference](xref:System.Text.Json)
-* [Write custom converters for System.Text.Json](system-text-json-converters-how-to.md)
+* [How to write custom converters](system-text-json-converters-how-to.md)
+* [How to migrate from Newtonsoft.Json](system-text-json-migrate-from-newtonsoft-how-to.md)
 * [DateTime and DateTimeOffset support in System.Text.Json](../datetime/system-text-json-support.md)
-* [GitHub issues in the dotnet/corefx repository labeled json-functionality-doc](https://github.com/dotnet/corefx/labels/json-functionality-doc) 
+* [System.Text.Json API reference](xref:System.Text.Json)
+<!-- * [System.Text.Json roadmap](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Text.Json/roadmap/README.md)-->