-Documentation

Doc/SerializationSettings.aml

@@ -338,6 +338,19 @@ or a property's object properties or collection items using
 </content>
 </section>
 
+<section>
+ <title>TraceWriter</title>
+ <content><para>The Json.NET serializer supports logging using the <codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference>
+      interface. By assigning a trace writer you can debug what is happening inside the Json.NET serializer when
+      serializing and deserializing JSON.</para>
+ <para>Read more about TraceWriters here: <externalLink>
+<linkText>Debug with Serialization Tracing</linkText>
+<linkUri>SerializationTracing.htm</linkUri>
+<linkTarget>_self</linkTarget>
+</externalLink></para>
+</content>
+</section>
+
 <section>
  <title>Error</title>
  <content><para>The <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference> event can catch errors during serialization and either handle the event and continue with

Doc/SerializationTracing.aml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="SerializationTracing" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <introduction>
+      <para>The Json.NET serializer supports logging using the <codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference>
+      interface. By assigning a trace writer you can debug what is happening inside the Json.NET serializer when
+      serializing and deserializing JSON.</para>
+    </introduction>
+    <section>
+      <title>ITraceWriter</title>
+      <content>
+        <para>A trace writer can be assigned using properties on JsonSerializerSettings or JsonSerializer.</para>
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\TraceWriterTests.cs" region="MemoryTraceWriterExample" title="Debugging serialization using MemoryTraceWriter" />
+        
+        <para>Json.NET has two implementations of ITraceWriter: <codeEntityReference>P:Newtonsoft.Json.Serialization.MemoryTraceWriter</codeEntityReference>
+        which keeps messages in memory for simple debugging like the example
+        above, and <codeEntityReference>T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter</codeEntityReference> which writes messages to any
+        System.Diagnostics.TraceListeners your application is using.</para>
+      </content>
+    </section>
+    <section>
+      <title>Custom ITraceWriter</title>
+      <content>
+        <para>To write messages using your existing logging framework implement a custom version of ITraceWriter.</para>
+
+<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\TraceWriterTests.cs" region="CustomTraceWriterExample" title="Custom NLog TraceWriter" />
+        
+      </content>
+    </section>
+    <relatedTopics>
+      <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.MemoryTraceWriter</codeEntityReference>
+      <codeEntityReference>T:Newtonsoft.Json.Serialization.DiagnosticsTraceWriter</codeEntityReference>
+    </relatedTopics>
+  </developerConceptualDocument>
+</topic>

Doc/doc.content

@@ -13,8 +13,9 @@
     <Topic id="DatesInJSON" visible="True" title="Serializing Dates in JSON" />
     <Topic id="ReducingSerializedJSONSize" visible="True" title="Reducing Serialized JSON Size" />
     <Topic id="SerializingJSONFragments" visible="True" title="Serializing Partial JSON Fragments" />
-    <Topic id="ConditionalProperties" visible="True" isSelected="true" title="Conditional Property Serialization" />
+    <Topic id="ConditionalProperties" visible="True" title="Conditional Property Serialization" />
     <Topic id="ContractResolver" visible="True" title="Serialization using ContractResolver" />
+    <Topic id="SerializationTracing" visible="True" isSelected="true" title="Debug with Serialization Tracing" />
   </Topic>
   <Topic id="LINQtoJSON" visible="True" title="LINQ to JSON">
     <Topic id="ParsingLINQtoJSON" visible="True" title="Parsing JSON" />

Doc/doc.shfbproj

@@ -137,6 +137,7 @@
     <Content Include="donate.gif" />
   </ItemGroup>
   <ItemGroup>
+    <None Include="SerializationTracing.aml" />
     <None Include="JsonNetVsDotNetSerializers.aml" />
     <None Include="JsonNetVsWindowsDataJson.aml" />
     <None Include="ConditionalProperties.aml" />