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

<content><para><codeEntityReference>T:Newtonsoft.Json.MissingMemberHandling</codeEntityReference> controls how missing members, e.g. JSON contains a property that isn't a member on the object, are handled during deserialization.</para>

<table>

<row>

<entry><para>Member</para></entry>

<entry><para>Description</para></entry>

</row>

</tableHeader>

<row>

<entry><para><legacyBold>Ignore</legacyBold></para></entry>

<entry><para>By default Json.NET ignores JSON if there is no field or property for its value to be set to during deserialization.</para></entry>

</row>

<row>

<entry><para><legacyBold>Error</legacyBold></para></entry>

<entry><para>Json.NET errors when there is a missing member during deserialization.</para></entry>

</row>

</table>

</content>

</section>

<title>ReferenceLoopHandling</title>

<para><codeEntityReference>T:Newtonsoft.Json.ReferenceLoopHandling</codeEntityReference> controls how circular referencing objects,

e.g. a Person object referencing itself via a Manager property, are serialized.</para>

<para>The <codeEntityReference>M:System.Object.Equals(System.Object)</codeEntityReference> method is used to test whether an object is in a circular reference.

By default <codeInline>Object.Equals(Object)</codeInline> will test whether the references are equal for reference types and private and public values

are equal for value types. Classes and structs can override this method.</para>

<table>

<row>

<entry><para>Member</para></entry>

<entry><para>Description</para></entry>

</row>

</tableHeader>

<row>

<entry><para>Error</para></entry>

<entry><para>By default Json.NET will error if a reference loop is encountered (otherwise the serializer will get into an infinite loop).</para></entry>

</row>

<row>

<entry><para>Ignore</para></entry>

<entry><para>Json.NET will ignore objects in reference loops and not serialize them. The first time an object is encountered it will be serialized as usual but if the object is encountered as a child object of itself the serializer will skip serializing it.</para></entry>

</row>

<row>

<entry><para>Serialize</para></entry>

<entry><para>This option forces Json.NET to serialize objects in reference loops. This is useful if objects are nested but not indefinitely.</para></entry>

</row>

</table>

<para>ReferenceLoopHandling can be used as an argument when calling the serializer, it can be set on an object's properties or

a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemReferenceLoopHandling</codeEntityReference>,

customized on a property with <codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ReferenceLoopHandling</codeEntityReference>

or a property's object properties or collection items using

<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemReferenceLoopHandling</codeEntityReference>.</para>

</content>

</section>

<title>NullValueHandling</title>

100

<content><para><codeEntityReference>T:Newtonsoft.Json.NullValueHandling</codeEntityReference> controls how null values on .NET objects are handled during serialization and how null values in JSON are handled during deserialization.</para>

101

102

<table>

103

104

<row>

105

<entry><para>Member</para></entry>

106

<entry><para>Description</para></entry>

107

</row>

108

</tableHeader>

109

<row>

110

<entry><para>Include</para></entry>

111

<entry><para>By default Json.NET writes null values to JSON when serializing and sets null values to fields/properties when deserializing.</para></entry>

112

</row>

113

<row>

114

<entry><para>Ignore</para></entry>

115

<entry><para>Json.NET will skip writing JSON properties if the .NET value is null when serializing and will skip setting fields/properties if the JSON property is null when deserializing.</para></entry>

116

</row>

117

</table>

118

<para>NullValueHandling can also be customized on individual properties with JsonPropertyAttribute.</para>

119

120

</content>

121

</section>

122

123

124

<title>DefaultValueHandling</title>

125

<content><para><codeEntityReference>T:Newtonsoft.Json.DefaultValueHandling</codeEntityReference> controls how Json.NET uses default values set using the .NET <codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference> when serializing and deserializing.</para>

126

127

<table>

128

129

<row>

130

<entry><para>Member</para></entry>

131

<entry><para>Description</para></entry>

132

</row>

133

</tableHeader>

134

<row>

135

<entry><para><legacyBold>Include</legacyBold></para></entry>

136

<entry><para>By default Json.NET will write a field/property value to JSON when serializing if the value is the same as the field/property's default value.

137

The Json.NET deserializer will continue setting a field/property if the JSON value is the same as the default value.</para></entry>

138

</row>

139

<row>

140

<entry><para><legacyBold>Ignore</legacyBold></para></entry>

141

<entry><para>Json.NET will skip writing a field/property value to JSON if the value is the same as the field/property's default value, or the custom

142

value specified in <codeEntityReference>T:System.ComponentModel.DefaultValueAttribute</codeEntityReference> if the attribute is present. The Json.NET deserializer

143

will skip setting a .NET object's field/property if the JSON value is the same as the default value.</para></entry>

144

</row>

145

</table>

146

<para>DefaultValueHandling can also be customized on individual properties with JsonPropertyAttribute.</para>

147

148

</content>

149

</section>

150

151

152

<title>ObjectCreationHandling</title>

153

<content><para><codeEntityReference>T:Newtonsoft.Json.ObjectCreationHandling</codeEntityReference> controls how objects are created and deserialized to during deserialization.</para>

154

155

<table>

156

157

<row>

158

<entry><para>Member</para></entry>

159

<entry><para>Description</para></entry>

160

</row>

161

</tableHeader>

162

<row>

163

164

<entry><para>By default Json.NET will attempt to set JSON values onto existing objects and add JSON values to existing collections during deserialization. </para></entry>

165

</row>

166

<row>

167

<entry><para><legacyBold>Reuse</legacyBold></para></entry>

168

<entry><para>Same behaviour as auto.</para></entry>

169

</row>

170

<row>

171

<entry><para><legacyBold>Replace</legacyBold></para></entry>

172

<entry><para>Json.NET will always recreate objects and collections before setting values to them during deserialization.</para></entry>

173

</row>

174

</table>

175

<para>ObjectCreationHandling can also be customized on individual properties with JsonPropertyAttribute.</para>

176

177

</content>

178

</section>

179

180

181

<title>TypeNameHandling</title>

182

183

<para>

184

<codeEntityReference>T:Newtonsoft.Json.TypeNameHandling</codeEntityReference> controls whether Json.NET includes .NET type names

185

during serialization with a $type property and reads .NET type names from that property to determine what type to create during

186

deserialization.

187

</para>

188

<para>

189

The value of the $type property can be customized by creating your own

190

<codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference>.

191

</para>

192

193

<table>

194

195

<row>

196

<entry><para>Member</para></entry>

197

<entry><para>Description</para></entry>

198

</row>

199

</tableHeader>

200

<row>

201

202

<entry><para>By default Json.NET does not read or write type names during deserialization.</para></entry>

203

</row>

204

<row>

205

<entry><para><legacyBold>Objects</legacyBold></para></entry>

206

<entry><para>Json.NET will write and use type names for objects but not collections.</para></entry>

207

</row>

208

<row>

209

<entry><para><legacyBold>Arrays</legacyBold></para></entry>

210

<entry><para>Json.NET will write and use type names for collections but not objects.</para></entry>

211

</row>

212

<row>

213

214

<entry><para>Json.NET will check whether an object/collection matches its declared property and writes the type name if they do not match, e.g. a property with a type of Mammal has a derived instance of Dog assigned. Auto will ensure that type information isn't lost when serializing/deserializing automatically without having to write type names for every object.</para></entry>

215

</row>

216

<row>

217

218

<entry><para>Json.NET will write and use type names for objects and collections.</para></entry>

219

</row>

220

</table>

221

<para>TypeNameHandling can be used as an argument when calling the serializer, it can be set on an object's properties or

222

a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemTypeNameHandling</codeEntityReference>,

223

customized on a property with <codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.TypeNameHandling</codeEntityReference>

224

or a property's object properties or collection items using

225

<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemTypeNameHandling</codeEntityReference>.</para>

226

</content>

227

</section>

228

229

230

<title>TypeNameAssemblyFormat</title>

231

<content><para><codeEntityReference>T:System.Runtime.Serialization.Formatters.FormatterAssemblyStyle</codeEntityReference> controls how type names are written during serialization.</para>

232

233

<table>

234

235

<row>

236

<entry><para>Member</para></entry>

237

<entry><para>Description</para></entry>

238

</row>

239

</tableHeader>

240

<row>

241

<entry><para><legacyBold>Simple</legacyBold></para></entry>

242

<entry><para>By default Json.NET writes the partial assembly name with the type, e.g. System.Data.DataSet, System.Data. Note that Silverlight and Windows Phone are not able to use this format.</para></entry>

243

</row>

244

<row>

245

246

<entry><para>Json.NET will write the full assembly name, including version number, culture and public key token.</para></entry>

247

</row>

248

</table>

249

<para>Read more about the valid values at <codeEntityReference>T:System.Runtime.Serialization.Formatters.FormatterAssemblyStyle</codeEntityReference>.</para>

250

251

</content>

252

</section>

253

254

255

<title>Binder</title>

256

<content><para>The <codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference> is used to resolve type names to a .NET type.</para>

257

<para>Read more about the serialization binder here: <codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference></para>

258

</content>

259

</section>

260

261

262

<title>ConstructorHandling</title>

263

<content><para><codeEntityReference>T:Newtonsoft.Json.ConstructorHandling</codeEntityReference> controls how constructors are used when initializing objects during deserialization.</para>

264

265

<table>

266

267

<row>

268

<entry><para>Member</para></entry>

269

<entry><para>Description</para></entry>

270

</row>

271

</tableHeader>

272

<row>

273

<entry><para><legacyBold>Default</legacyBold></para></entry>

274

<entry><para>By default Json.NET will first look for a constructor marked with the JsonConstructorAttribute, then look for a public default constructor

275

(a constructor that doesn't take any arguments), then check if the class has a single public constructor with arguments and finally check for a

276

non-public default constructor. If the class has multiple public constructors with arguments an error will be thrown. This can be fixed by

277

marking one of the constructors with the JsonConstructorAttribute.</para></entry>

278

</row>

279

<row>

280

<entry><para><legacyBold>AllowNonPublicDefaultConstructor</legacyBold></para></entry>

281

<entry><para>Json.NET will use a classes private default constructor before constructors with arguments if available. </para></entry>

282

</row>

283

</table>

284

285

</content>

286

</section>

287

288

289

<title>Converters</title>

290

<content><para>This is the collection of JsonConverters that will be used during serialization and deserialization.</para>

291

<para>A <codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference> allows JSON to be manually written during serialization and read during deserialization.

292

This is useful for particularly complex JSON structures or for when you want to change how a type is serialized.</para>

293

<para>When a JsonConverter has been added to a JsonSerializer it will be checked for every value that is being serialized/deserialized

294

using its CanConvert to see if it should be used. If CanConvert returns true then the JsonConverter will be used to read or write

295

the JSON for that value. Note that while a JsonConverter gives you complete control over that values JSON, many Json.NET serialization

296

features are no longer available like type name and reference handling.</para>

297

298

<para>JsonConverters can be used as an argument when calling the serializer, it can be set on an object or property

299

using <codeEntityReference>T:Newtonsoft.Json.JsonConverterAttribute</codeEntityReference>, it be set on an object's properties or

300

a collection's items using <codeEntityReference>P:Newtonsoft.Json.JsonContainerAttribute.ItemConverterType</codeEntityReference>,

301

or a property's object properties or collection items using

302

<codeEntityReference>P:Newtonsoft.Json.JsonPropertyAttribute.ItemConverterType</codeEntityReference>.</para>

303

304

<para>To create your own custom converter inherit from the JsonConverter class. Read more about the built-in JsonConverters below:</para>

305

306

307

<linkText>Serializing Dates in JSON</linkText>

308

<linkUri>DatesInJSON.htm</linkUri>

309

310

</externalLink></para></listItem>

311

312

<linkText>Converting between JSON and XML</linkText>

313

<linkUri>ConvertingJSONandXML.htm</linkUri>

314

315

</externalLink></para></listItem>

316

317

<linkText>CustomCreationConverter</linkText>

318

<linkUri>CustomCreationConverter.htm</linkUri>

319

320

</externalLink></para></listItem>

321

<listItem><para><codeEntityReference>T:Newtonsoft.Json.Converters.StringEnumConverter</codeEntityReference></para></listItem>

322

</list>

323

324

325

</content>

326

</section>

327

328

329

<title>ContractResolver</title>

330

<content><para>Internally for every .NET type the JsonSerializer will create a contract of how the type should be serialized and deserialized,

331

based on type metadata and attributes applied to the class. Specifying a custom <codeEntityReference>T:Newtonsoft.Json.Serialization.IContractResolver</codeEntityReference>

332

allows the creation of contracts to be customized.</para>

333

<para>Read more about Contract Resolvers here: <externalLink>

334

<linkText>Contract Resolvers</linkText>

335

<linkUri>ContractResolver.htm</linkUri>

336

337

</externalLink></para>

338

</content>

339

</section>

340

341

342

<title>TraceWriter</title>

343

<content><para>The Json.NET serializer supports logging and debugging using the

344

<codeEntityReference>T:Newtonsoft.Json.Serialization.ITraceWriter</codeEntityReference> interface.

345

By assigning a trace writer you can debug what happens inside the Json.NET serializer when serializing and deserializing JSON.</para>

346

<para>Read more about TraceWriters here: <externalLink>

347

<linkText>Debugging with Serialization Tracing</linkText>

348

<linkUri>SerializationTracing.htm</linkUri>

349

350

</externalLink></para>

351

</content>

352

</section>

353

354

355

<title>Error</title>

356

<content><para>The <codeEntityReference>E:Newtonsoft.Json.JsonSerializer.Error</codeEntityReference> event can catch errors during serialization and either handle the event and continue with

357

serialization or let the error bubble up and be thrown to the application.</para>

358

<para>Read more about error handling here: <externalLink>

359

<linkText>Serialization Error Handling</linkText>

360

<linkUri>SerializationErrorHandling.htm</linkUri>

361

362

</externalLink>

363

</para>

364

</content>

365

</section>

366

</sections>

367

368

369

<linkText>Serialization Guide</linkText>

370

<linkUri>SerializationGuide.htm</linkUri>

371

372

</externalLink>

373

374

<linkText>Serialization Attributes</linkText>

375

<linkUri>SerializationAttributes.htm</linkUri>

376

377

</externalLink>

378

379

<linkText>Serializing Dates in JSON</linkText>

380

<linkUri>DatesInJSON.htm</linkUri>

381

382

</externalLink>

383

384

<codeEntityReference>T:Newtonsoft.Json.JsonSerializer</codeEntityReference>

385

<codeEntityReference>T:Newtonsoft.Json.JsonSerializerSettings</codeEntityReference>

386

<codeEntityReference>T:Newtonsoft.Json.JsonConverter</codeEntityReference>

387

<codeEntityReference>T:System.Runtime.Serialization.SerializationBinder</codeEntityReference>

388

</relatedTopics>

389

</developerConceptualDocument>

390

</topic>

b'\\ No newline at end of file'

Older »