@@ -21,34 +21,40 @@ namespace Tests.ClientConcepts.HighLevel.Serialization
2121 /**[[custom-serialization]]
2222 * === Custom Serialization
2323 *
24- * NEST 6.x ships with a _shaded_ Json.NET dependency, meaning that all of Json.NET's types are
25- * internalized and IL merged into the NEST assembly, and their namespace has been changed
26- * from `Newtonsoft.Json` to `Nest.Json`.
24+ * After internalizing the serialization routines, and IL-merging the Newtonsoft.Json package in 6.x, we are pleased to
25+ * announce that the next stage of serialization improvements have been completed in 7.0.
2726 *
28- * Why would we do this, you may ask? Well, NEST has always isolated its dependency on Json.NET as best as it could,
29- * but this meant that we had to mandate how certain things were in the client. For instance,
30- * NEST heavily relied on the fact that the `IContractResolver` used by the configured serializer was
31- * an instance of `ElasticContractResolver`, so if you wanted to deserialize your `_source` or `_fields`
32- * using your own resolver, you were out of luck. In addition, continued improvements to NEST's serialization pipeline
33- * was stymied by this dependency and as client authors, we wanted to unhinder ourselves from this in order to explore the myriad
34- * of exciting developments happening in the .NET ecosystem around performance with the likes of `Span<T>`,
35- * `ArrayPool<T>` and a more compact UTF-8 string representation.
27+ * Both SimpleJson and Newtonsoft.Json have been completely removed and replaced with an implementation of Utf8Json, a fast
28+ * serializer that works directly with UTF-8 binary.
3629 *
37- * So what did we do in 6.x and how does it affect you?
30+ * With the move to Utf8Json, we have removed some features that were available in the previous JSON libraries that have
31+ * proven too onerous to carry forward at this stage.
3832 *
39- * The `NEST` nuget package from 6.0.0 onwards will use the internal Json.NET serializer and will in effect, behave the same
40- * as it did in previous releases. If you previously relied on custom Json.NET serialization and configuration with custom
41- * `JsonSerializerSettings` and `JsonConverter` types for example, things have changed a bit. The following section explains
42- * how to continue working with these with NEST 6.x.
33+ * - JSON in the request is never indented, even if SerializationFormatting.Indented is specified. The serialization
34+ * routines generated by Utf8Json never generate an IJsonFormatter<T> that will indent JSON, for performance reasons.
35+ * We are considering options for exposing indented JSON for development and debugging purposes.
36+ *
37+ * - NEST types cannot be extended by inheritance. With NEST 6.x, additional properties can be included for a type by deriving from
38+ * that type and annotating these new properties. With the current implementation of serialization with Utf8Json, this approach will not work.
39+ *
40+ * - Serializer uses Reflection.Emit. Utf8Json uses Reflection.Emit to generate efficient formatters for serializing types that it sees.
41+ * Reflection.Emit is not supported on all platforms, for example, UWP, Xamarin.iOS, and Xamarin.Android.
42+ *
43+ * - Elasticsearch.Net.DynamicResponse deserializes JSON arrays to List<object>. SimpleJson deserialized JSON arrays to object[],
44+ * but Utf8Json deserializes them to List<object>. This change is preferred for allocation and performance reasons.
45+ *
46+ * - Utf8Json is much stricter when deserializing JSON object field names to C# POCO properties. With the internal Json.NET serializer
47+ * in 6.x, JSON object field names would attempt to be matched with C# POCO property names first by an exact match, falling back to a
48+ * case insensitive match. With Utf8Json in 7.x however, JSON object field names must match exactly the name configured for the
49+ * C# POCO property name.
4350 */
4451 public class GettingStarted
4552 {
4653 /**[float]
4754 * ==== Injecting a new serializer
4855 *
49- * Starting with NEST 6.x you can inject a serializer that is isolated to only be called
50- * for the (de)serialization of `_source`, `_fields`, or wherever a user provided value is expected
51- * to be written and returned.
56+ * You can inject a serializer that is isolated to only be called for the (de)serialization of `_source`, `_fields`, or
57+ * wherever a user provided value is expected to be written and returned.
5258 *
5359 * Within NEST, we refer to this serializer as the `SourceSerializer`.
5460 *
@@ -114,8 +120,10 @@ public class MyPercolationDocument
114120 *
115121 * We ship a separate {nuget}/NEST.JsonNetSerializer[NEST.JsonNetSerializer] package that helps in composing a custom `SourceSerializer`
116122 * using `Json.NET`, that is smart enough to delegate the serialization of known NEST types back to the built-in
117- * `RequestResponseSerializer`. This package is also useful if you want to control how your documents and values are stored
118- * and retrieved from Elasticsearch using `Json.NET`, without interfering with the way NEST uses `Json.NET` internally.
123+ * `RequestResponseSerializer`. This package is also useful if
124+ *
125+ * . You want to control how your documents and values are stored and retrieved from Elasticsearch using `Json.NET`
126+ * . You want to use `Newtonsoft.Json.Linq` types such as `JObject` within your documents
119127 *
120128 * The easiest way to hook this custom source serializer up is as follows
121129 */
0 commit comments