SerializationTracing.aml

<?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 and debugging using the
      <codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference> interface.
      By assigning a trace writer you can capture serialization messages and errors, and debug what happens 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>T: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 just 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>