New article - Migrate from Newtonsoft.Json

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

@@ -20,11 +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:
-
-* [Deserialize inferred types to Object properties](#deserialize-inferred-types-to-object-properties).
-* [Support Dictionary with non-string key](#support-dictionary-with-non-string-key).
-* [Support polymorphic deserialization](#support-polymorphic-deserialization).
+You can also write custom converters to extend `System.Text.Json` with functionality not included in the current release. For more information, see [How to migrate from Newtonsoft Json.NET to System.Text.Json](system-text-json-migrate-from-newtonsoft-how-to.md).
 
 ## Custom converter patterns
 
@@ -56,18 +52,16 @@ The following code shows a custom converter that works with `Dictionary<Enum,TVa
 
 [!code-csharp[](~/samples/snippets/core/system-text-json/csharp/DictionaryTKeyEnumTValueConverter.cs)]
 
-The preceding code is the same as what is shown in the [Support Dictionary with non-string key](#support-dictionary-with-non-string-key) later in this article.
-
 ## Steps to follow the basic pattern
 
 The following steps explain how to create a converter by following the basic pattern:
 
 * 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 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 [Polymorphic deserialization](system-text-json-migrate-from-newtonsoft-how-to.md#polymorphic-deserialization).
 
-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/master/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/) as reference implementations for writing custom converters.
 
 ## Steps to follow the factory pattern
 
@@ -166,135 +160,24 @@ If multiple custom converters for a type are registered in the `Converters` coll
 
 A built-in converter is chosen only if no applicable custom converter is registered.
 
-## Converter samples for common scenarios
-
-The following sections provide converter samples that address some common scenarios that built-in functionality doesn't handle.
-
-* [Deserialize inferred types to Object properties](#deserialize-inferred-types-to-object-properties)
-* [Support Dictionary with non-string key](#support-dictionary-with-non-string-key)
-* [Support polymorphic deserialization](#support-polymorphic-deserialization)
-
-### Deserialize inferred types to Object properties
-
-When deserializing to a property of type `Object`, a `JsonElement` object is created. The reason is that the deserializer doesn't know what CLR type to create, and it doesn't try to guess. For example, if a JSON property has "true", the deserializer doesn't infer that the value is a `Boolean`, and if an element has "01/01/2019", the deserializer doesn't infer that it's a `DateTime`.
-
-Type inference can be inaccurate. If the deserializer parses a JSON number that has no decimal point as a `long`, that might result in out-of-range issues if the value was originally serialized as a `ulong` or `BigInteger`. Parsing a number that has a decimal point as a `double` might lose precision if the number was originally serialized as a `decimal`.
-
-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`
-* Dates to `DateTime`
-* Strings to `string`
-* Everything else to `JsonElement`
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/ObjectToInferredTypesConverter.cs)]
-
-The following code registers the converter:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/ConvertInferredTypesToObject.cs?name=SnippetRegister)]
-
-Here's an example type with `Object` properties:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/WeatherForecast.cs?name=SnippetWFWithObjectProperties)]
-
-The following example of JSON to deserialize contains values that will be deserialized as `DateTime`, `long`, and `string`:
-
-```json
-{
-  "Date": "2019-08-01T00:00:00-07:00",
-  "TemperatureCelsius": 25,
-  "Summary": "Hot",
-}
-```
-
-Without the custom converter, deserialization puts a `JsonElement` in each property.
-
-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 deserialization to Object properties.
-
-### Support Dictionary with non-string key
-
-The built-in support for dictionary collections is for `Dictionary<string, TValue>`. That is, the key must be a string. To support a dictionary with an integer or some other type as the key, a custom converter is required.
-
-The following code shows a custom converter that works with `Dictionary<Enum,TValue>`:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/DictionaryTKeyEnumTValueConverter.cs)]
-
-The following code registers the converter:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/ConvertDictionaryTkeyEnumTValue.cs?name=SnippetRegister)]
-
-The converter can serialize and deserialize the `TemperatureRanges` property of the following class that uses the following `Enum`:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/WeatherForecast.cs?name=SnippetWFWithEnumDictionary)]
-
-The JSON output from serialization looks like the following example:
-
-```json
-{
-  "Date": "2019-08-01T00:00:00-07:00",
-  "TemperatureCelsius": 25,
-  "Summary": "Hot",
-  "TemperatureRanges": {
-    "Cold": 20,
-    "Hot": 40
-  }
-}
-```
-
-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.
-
-### Support polymorphic deserialization
-
-[Polymorphic serialization](system-text-json-how-to.md#serialize-properties-of-derived-classes) doesn't require a custom converter, but deserialization does require a custom converter.
-
-Suppose, for example, you have a `Person` abstract base class, with `Employee` and `Customer` derived classes. Polymorphic deserialization means that at design time you can specify `Person` as the deserialization target, and `Customer` and `Employee` objects in the JSON are correctly deserialized at runtime. During deserialization, you have to find clues that identify the required type in the JSON. The kinds of clues available vary with each scenario. For example, a discriminator property might be available or you might have to rely on the presence or absence of a particular property. The current release of `System.Text.Json` doesn't provide attributes to specify how to handle polymorphic deserialization scenarios, so custom converters are required.
-
-The following code shows a base class, two derived classes, and a custom converter for them. The converter uses a discriminator property to do polymorphic deserialization. The type discriminator isn't in the class definitions but is created during serialization and is read during deserialization.
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/Person.cs?name=SnippetPerson)]
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/PersonConverterWithTypeDiscriminator.cs)]
-
-The following code registers the converter:
-
-[!code-csharp[](~/samples/snippets/core/system-text-json/csharp/ConvertPolymorphic.cs?name=SnippetRegister)]
-
-The converter can deserialize JSON that was created by using the same converter to serialize, for example:
-
-```json
-[
-  {
-    "TypeDiscriminator": 1,
-    "CreditLimit": 10000,
-    "Name": "John"
-  },
-  {
-    "TypeDiscriminator": 2,
-    "OfficeNumber": "555-1234",
-    "Name": "Nancy"
-  }
-]
-```
-
 ## 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.NET](system-text-json-how-to.md) article contains samples of custom converters.
+
+The [unit tests folder](https://github.com/dotnet/runtime/blob/master/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/master/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters) to serve as a starting point for customization.
+
 ## Additional resources
 
 * [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)
+* [Source code for built-in converters](https://github.com/dotnet/runtime/tree/master/src/libraries/System.Text.Json/src/System/Text/Json/Serialization/Converters/)
+* [GitHub issue related to custom converters](https://github.com/dotnet/corefx/issues/36639)

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

@@ -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).
+For information about polymorphic deserialization, see [Polymorphic deserialization](system-text-json-migrate-from-newtonsoft-how-to.md#polymorphic-deserialization).
 
 ## Allow comments and trailing commas