100 lines
6.0 KiB
XML
100 lines
6.0 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="SerializationErrorHandling" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<!--
|
|
<summary>
|
|
<para>Optional summary abstract</para>
|
|
</summary>
|
|
-->
|
|
<introduction>
|
|
<!-- Uncomment this to generate an outline of the section and sub-section
|
|
titles. Specify a numeric value as the inner text to limit it to
|
|
a specific number of sub-topics when creating the outline. Specify
|
|
zero (0) to limit it to top-level sections only. -->
|
|
<!-- <autoOutline /> -->
|
|
<para>Json.NET supports error handling during serialization and
|
|
deserialization. Error handling lets you catch an error and
|
|
choose whether to handle it and continue with serialization or
|
|
let the error bubble up and be thrown in your application.</para>
|
|
<para>Error handling is defined through two methods: the <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference> event on
|
|
JsonSerializer and the <codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>.</para>
|
|
<autoOutline lead="none" excludeRelatedTopics="true" />
|
|
</introduction>
|
|
<!-- Add one or more top-level section elements. These are collapsible.
|
|
If using <autoOutline />, add an address attribute to identify it
|
|
and specify a title so that it can be jumped to with a hyperlink. -->
|
|
<section address="ErrorEvent">
|
|
<title>Error Event</title>
|
|
<content>
|
|
<!-- Uncomment this to create a sub-section outline
|
|
<autoOutline /> -->
|
|
<para>The <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference>
|
|
event is an event handler found on <codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>.
|
|
The error event is raised whenever an exception is thrown while serializing
|
|
or deserializing JSON. Like all settings found on JsonSerializer, it can also
|
|
be set on <codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>
|
|
and passed to the serialization methods on JsonConvert.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandling" title="Serialization Error Handling" />
|
|
|
|
<para>In this example we are deserializing a JSON array to a collection
|
|
of DateTimes. On the JsonSerializerSettings a handler has been assigned
|
|
to the <codeInline>Error</codeInline> event which will log the error message and mark the error
|
|
as handled.</para>
|
|
|
|
<para>The result of deserializing the JSON is three successfully deserialized
|
|
dates and three error messages: one for the badly formatted string ("I am
|
|
not a date and will error!"), one for the nested JSON array, and one for the
|
|
null value since the list doesn't allow nullable DateTimes. The event
|
|
handler has logged these messages and Json.NET has continued on deserializing
|
|
the JSON because the errors were marked as handled.</para>
|
|
|
|
<para>One thing to note with error handling in Json.NET is that an
|
|
unhandled error will bubble up and raise the event on each of its
|
|
parents. For example an unhandled error when serializing a collection of objects
|
|
will be raised twice, once against the object and then again on the collection.
|
|
This will let you handle an error either where it occurred or on one of its
|
|
parents.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandlingWithParent" title="Parent Error Handling" />
|
|
|
|
<para>If you aren't immediately handling an error and only want to
|
|
perform an action against it once, then you can check to see whether the
|
|
<codeEntityReference>T:Newtonsoft.Json.Serialization.ErrorEventArgs</codeEntityReference>'s
|
|
CurrentObject is equal to the OriginalObject.
|
|
OriginalObject is the object that threw the error and CurrentObject is
|
|
the object that the event is being raised against. They will only equal
|
|
the first time the event is raised against the OriginalObject.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="OnErrorAttribute">
|
|
<title>OnErrorAttribute</title>
|
|
<content>
|
|
<!-- Uncomment this to create a sub-section outline
|
|
<autoOutline /> -->
|
|
<para>The <codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>
|
|
works much like the other <link xlink:href="SerializationAttributes">.NET serialization attributes</link>
|
|
that Json.NET supports. To use it you simply place the
|
|
attribute on a method that takes the correct parameters: a
|
|
StreamingContext and an ErrorContext. The name of the method doesn't
|
|
matter.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandlingAttributeObject" title="Serialization Error Handling Attribute" />
|
|
|
|
<para>In this example accessing the Roles property will throw an
|
|
exception when no roles have been set. The HandleError method will set
|
|
the error when serializing Roles as handled and allow Json.NET to
|
|
continue serializing the class.</para>
|
|
|
|
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\SerializationTests.cs" region="SerializationErrorHandlingAttributeExample" title="Serialization Error Handling Example" />
|
|
|
|
</content>
|
|
</section>
|
|
<relatedTopics>
|
|
<link xlink:href="SerializationAttributes" />
|
|
<codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference>
|
|
<codeEntityReference>T:Newtonsoft.Json.Serialization.OnErrorAttribute</codeEntityReference>
|
|
</relatedTopics>
|
|
</developerConceptualDocument>
|
|
</topic> |