rewrote documentation on settings custom json.net settings

Author: Mpdreamz

src/Nest/CommonAbstractions/SerializationBehavior/ElasticContractResolver.cs

@@ -14,13 +14,13 @@ namespace Nest
 	public class ElasticContractResolver : DefaultContractResolver
 	{
 		private readonly IList<Func<Type, JsonConverter>> _contractConverters;
-		public static JsonSerializer Empty { get; } = new JsonSerializer();
-
+		public static JsonSerializer Empty { get; } = new JsonSerializer();
+
 		/// <summary>
 		/// ConnectionSettings can be requested by JsonConverter's.
 		/// </summary>
-		public IConnectionSettingsValues ConnectionSettings { get; private set; }
-
+		public IConnectionSettingsValues ConnectionSettings { get; private set; }
+
 		/// <summary>
 		/// Signals to custom converter that it can get serialization state from one of the converters. Ugly but massive performance gain
 		/// </summary>
@@ -36,22 +36,22 @@ protected override JsonContract CreateContract(Type objectType)
 		{
 			// cache contracts per connection settings
 			return this.ConnectionSettings.Inferrer.Contracts.GetOrAdd(objectType, o =>
-			{				
-				var contract = base.CreateContract(o);
-				
+			{
+				var contract = base.CreateContract(o);
+
 				if (typeof(IDictionary).IsAssignableFrom(o) && !typeof(IIsADictionary).IsAssignableFrom(o))
 					contract.Converter = new VerbatimDictionaryKeysJsonConverter();
 				if (typeof(IEnumerable<QueryContainer>).IsAssignableFrom(o))
 					contract.Converter = new QueryContainerCollectionJsonConverter();
 				else if (o == typeof(ServerError))
 					contract.Converter = new ServerErrorJsonConverter();
-				else if (o == typeof(DateTime) ||
-				         o == typeof(DateTime?) ||
-				         o == typeof(DateTimeOffset) ||
-				         o == typeof(DateTimeOffset?))
+				else if (o == typeof(DateTime) ||
+						 o == typeof(DateTime?) ||
+						 o == typeof(DateTimeOffset) ||
+						 o == typeof(DateTimeOffset?))
 					contract.Converter = new IsoDateTimeConverter();
-				else if (o == typeof(TimeSpan) ||
-				         o == typeof(TimeSpan?))
+				else if (o == typeof(TimeSpan) ||
+						 o == typeof(TimeSpan?))
 					contract.Converter = new TimeSpanConverter();
 
 				if (this._contractConverters.HasAny())
@@ -102,12 +102,12 @@ private IEnumerable<Type> TypeWithInterfaces(Type objectType)
 		}
 
 		protected override IList<JsonProperty> CreateProperties(Type type, MemberSerialization memberSerialization)
-		{
-			// Only serialize explicitly implemented IProperty properties on attribute types
+		{
+			// Only serialize explicitly implemented IProperty properties on attribute types
 			if (typeof(ElasticsearchPropertyAttributeBase).IsAssignableFrom(type))
-				return PropertiesOfInterface<IProperty>(type, memberSerialization);
-
-			// Descriptors implement properties explicitly, these are not picked up by default
+				return PropertiesOfInterface<IProperty>(type, memberSerialization);
+
+			// Descriptors implement properties explicitly, these are not picked up by default
 			if (typeof(IDescriptor).IsAssignableFrom(type))
 				return PropertiesOfAll(type, memberSerialization);
 
@@ -155,9 +155,9 @@ protected override string ResolvePropertyName(string fieldName)
 
 		protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization)
 		{
-			var property = base.CreateProperty(member, memberSerialization);
-
-			// Skip serialization of empty collections that has DefaultValueHandling set to Ignore.
+			var property = base.CreateProperty(member, memberSerialization);
+
+			// Skip serialization of empty collections that has DefaultValueHandling set to Ignore.
 			if (property.DefaultValueHandling.HasValue
 				&& property.DefaultValueHandling.Value == DefaultValueHandling.Ignore
 				&& !typeof(string).IsAssignableFrom(property.PropertyType)

src/Tests/ClientConcepts/LowLevel/Connecting.doc.cs

@@ -289,14 +289,37 @@ protected override HttpClientHandler CreateHttpClientHandler(RequestData request
 		}
 #endif
 
-		/**=== Overriding default Json.NET behavior
+		/**=== Overriding Json.NET settings
 		*
 		* Overriding the default Json.NET behaviour in NEST is an expert behavior but if you need to get to the nitty gritty, this can be really useful.
-		* First, create a subclass of the `JsonNetSerializer`
 		*/
+
+		/**
+		 * The easiest way is to create an instance of `SerializerFactory` that allows you to register a modification callback
+		 * in the constructor
+		 */
+		public void EasyWay()
+		{
+			var pool = new SingleNodeConnectionPool(new Uri("http://localhost:9200"));
+			var connectionSettings = new ConnectionSettings(
+				pool,
+				new HttpConnection(),
+				new SerializerFactory((jsonSettings, nestSettings) => jsonSettings.PreserveReferencesHandling = PreserveReferencesHandling.All));
+
+			var client = new ElasticClient(connectionSettings);
+		}
+
+
+		/**
+		 * A more involved and explicit way would be to implement your own JsonNetSerializer subclass.
+		 *
+		 * NOTE: this is subject to change in the next major release. NEST relies heavily on stateful deserializers (that have access to the original
+		 * request) for specialized features such a covariant search results. This requirement leaks into this abstraction.
+		 */
 		public class MyJsonNetSerializer : JsonNetSerializer
 		{
-			public MyJsonNetSerializer(IConnectionSettingsValues settings) : base(settings, (s, csv) => s.PreserveReferencesHandling = PreserveReferencesHandling.All) //<1> Call this constructor if you only need access to `JsonSerializerSettings` without state
+			public MyJsonNetSerializer(IConnectionSettingsValues settings)
+				: base(settings, (s, csv) => s.PreserveReferencesHandling = PreserveReferencesHandling.All) //<1> Call this constructor if you only need access to `JsonSerializerSettings` without state
 			{
 				OverwriteDefaultSerializers((s, cvs) => ModifySerializerSettings(s)); //<2> Call OverwriteDefaultSerializers if you need access to `JsonSerializerSettings` with state
 			}