← Back to branch summary

~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

« back to all changes in this revision

Viewing changes to external/Newtonsoft.Json/Doc/ConvertingJSONandXML.aml

  • Committer: Package Import Robot
  • Author(s): Jo Shields
  • Date: 2013-05-12 09:46:03 UTC
  • mto: This revision was merged to the branch mainline in revision 29.
  • Revision ID: package-import@ubuntu.com-20130512094603-mad323bzcxvmcam0
Tags: upstream-4.0.5+dfsg
Import upstream version 4.0.5+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
external/Newtonsoft.Json/Doc/ConvertingJSONandXML.aml
 
1
<?xml version="1.0" encoding="utf-8"?>
 
2
<topic id="ConvertingJSONandXML" revisionNumber="1">
 
3
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
 
4
    <introduction>
 
5
      <para>Json.NET supports converting JSON to XML and vice versa using the
 
6
      <codeEntityReference>T:Newtonsoft.Json.Converters.XmlNodeConverter</codeEntityReference>.</para>
 
7
      <para>Elements, attributes, text, comments, character data, processing instructions,
 
8
      namespaces and the XML declaration are all preserved when converting between the two. The
 
9
      only caveat is that it is possible to lose the order of differently named nodes at the
 
10
      same level when they are grouped together into an array.</para>
 
11
    </introduction>
 
12
    <section>
 
13
      <title>Conversion Rules</title>
 
14
      <content>
 
15
   
 
16
<list class="bullet">
 
17
  <listItem><para>Elements remain unchanged.</para></listItem>
 
18
  <listItem><para>Attributes are prefixed with an @ and should be at the start of the object.</para></listItem>
 
19
  <listItem><para>Single child text nodes are a value directly against an element, otherwise they are accessed via #text.</para></listItem>
 
20
  <listItem><para>The XML declaration and processing instructions are prefixed with ?.</para></listItem>
 
21
  <listItem><para>Charater data, comments, whitespace and significate whitespace nodes are accessed via
 
22
  #cdata-section, #comment, #whitespace and #significate-whitespace respectively.</para></listItem>
 
23
  <listItem><para>Multiple nodes with the same name at the same level are grouped together into an array.</para></listItem>
 
24
  <listItem><para>Empty elements are null.</para></listItem>
 
25
</list>
 
26
 
 
27
<para>If the XML created from JSON doesn't match what you want then you will need to convert it manually.
 
28
The best approach to do this is to load your JSON into a LINQ to JSON object like JObject or JArray and then use LINQ to create
 
29
an XDocument. The opposite process, using LINQ with an XDocument to create a JObject or JArray, also works.
 
30
Find out more about using LINQ to JSON with LINQ <externalLink>
 
31
<linkText>here</linkText>
 
32
<linkUri>QueryingLINQtoJSON.htm</linkUri>
 
33
<linkTarget>_self</linkTarget>
 
34
</externalLink>.</para>
 
35
 
 
36
<alert class="note">
 
37
  <para>The version of Json.NET being used in your application will change what XML conversion methods are available.
 
38
  SerializeXmlNode/DeserializeXmlNode are available when the framework supports XmlDocument,
 
39
  SerializeXNode/DeserializeXNode are available when the framework supports XDocument.</para>
 
40
</alert>
 
41
 
 
42
      </content>
 
43
    </section>
 
44
    <section>
 
45
      <title>SerializeXmlNode</title>
 
46
      <content>
 
47
   
 
48
       <para>The JsonConvert has two helper methods for converting between JSON and XML. The first is
 
49
       <codeEntityReference>Overload:Newtonsoft.Json.JsonConvert.SerializeXmlNode</codeEntityReference>.
 
50
       This method takes an XmlNode and serializes it to JSON text.</para>
 
51
 
 
52
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="SerializeXmlNode" title="Converting XML to JSON with SerializeXmlNode" />
 
53
 
 
54
       <para>Because multiple nodes with a the same name at the same level are grouped together into an array
 
55
       the convernsion process can produce different JSON depending on the number of nodes. For example if some
 
56
       XML for a user has a single <codeInline>&lt;Role&gt;</codeInline> node then that role will be text against
 
57
       a JSON <codeInline>"Role"</codeInline> property, but if the user has multiple <codeInline>&lt;Role&gt;</codeInline>
 
58
       nodes then the role values will be placed in a JSON array.</para>
 
59
       
 
60
       <para>To fix this situation a custom XML attribute can be added to force a JSON array to be created.</para>
 
61
 
 
62
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="ForceJsonArray" title="Attribute to Force a JSON Array" />
 
63
    </content>
 
64
    </section>
 
65
    <section>
 
66
      <title>DeserializeXmlNode</title>
 
67
      <content>
 
68
   
 
69
       <para>The second helper method on JsonConvert is
 
70
       <codeEntityReference>Overload:Newtonsoft.Json.JsonConvert.DeserializeXmlNode</codeEntityReference>.
 
71
       This method takes JSON text and deserializes it into a XmlNode.</para>
 
72
   
 
73
       <para>Because valid XML must have one root element the JSON passed to DeserializeXmlNode should
 
74
       have one property in the root JSON object. If the root JSON object has multiple properties then
 
75
       the overload that also takes an element name should be used. A root element with that name will
 
76
       be inserted into the deserialized XmlNode.</para>
 
77
 
 
78
<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\ConvertingJsonAndXmlTests.cs" region="DeserializeXmlNode" title="Converting JSON to XML with DeserializeXmlNode" />
 
79
 
 
80
      </content>
 
81
    </section>
 
82
    <relatedTopics>
 
83
      <codeEntityReference>T:Newtonsoft.Json.Converters.XmlNodeConverter</codeEntityReference>
 
84
      <codeEntityReference>T:Newtonsoft.Json.JsonConvert</codeEntityReference>
 
85
    </relatedTopics>
 
86
  </developerConceptualDocument>
 
87
</topic>
 
 
b'\\ No newline at end of file'