LitJson简介

LitJSON Quickstart Guide

• Introduction
• Quick Start
  • Mapping JSON to objects and vice versa
  • Readers and Writers
  • Configuring the library’s behaviour

Introduction

JSON is a simple, yet powerful notation to specify data. It defines simple scalar types such as boolean, number (integers and reals) and string, and a couple of data structures: arrays (lists) and objects (dictionaries). For more information on the JSON format, visit JSON.org.

LitJSON is written in C#, and it’s intended to be small, fast and easy to use. It was developed on a GNU/Linux environment, using the Mono framework.

Quick Start

Mapping JSON to objects and vice versa

In order to consume data in JSON format inside .Net programs, the natural approach that comes to mind is to use JSON text to populate a new instance of a particular class; either a custom one, built to match the structure of the input JSON text, or a more general one which acts as a dictionary.

Conversely, in order to build new JSON strings from data stored in objects, a simple export operation sounds like a good idea.

For this purpose, LitJSON includes the JsonMapper class, which provides two main methods used to do JSON-to-object and object-to-JSON conversions. These methods are JsonMapper.ToObjectand JsonMapper.ToJson.

Simple JsonMapper examples

As the following example demonstrates, the ToObject method has a generic variant, JsonMapper.ToObject<T>, that is used to specify the type of the object to be returned.

using LitJson;using System;public class Person{    // C# 3.0 auto-implemented properties    public string   Name     { get; set; }    public int      Age      { get; set; }    public DateTime Birthday { get; set; }}public class JsonSample{    public static void Main()    {        PersonToJson();        JsonToPerson();    }    public static void PersonToJson()    {        Person bill = new Person();        bill.Name = "William Shakespeare";        bill.Age  = 51;        bill.Birthday = new DateTime(1564, 4, 26);        string json_bill = JsonMapper.ToJson(bill);        Console.WriteLine(json_bill);    }    public static void JsonToPerson()    {        string json = @"            {                ""Name""     : ""Thomas More"",                ""Age""      : 57,                ""Birthday"" : ""02/07/1478 00:00:00""            }";        Person thomas = JsonMapper.ToObject<Person>(json);        Console.WriteLine("Thomas' age: {0}", thomas.Age);    }}

Output from the example:

{"Name":"William Shakespeare","Age":51,"Birthday":"04/26/1564 00:00:00"}Thomas' age: 57

Using the non-generic variant of JsonMapper.ToObject

When JSON data is to be read and a custom class that matches a particular data structure is not available or desired, users can use the non-generic variant of ToObject, which returns a JsonDatainstance. JsonData is a general purpose type that can hold any of the data types supported by JSON, including lists and dictionaries.

using LitJson;using System;public class JsonSample{    public static void Main()    {        string json = @"          {            ""album"" : {              ""name""   : ""The Dark Side of the Moon"",              ""artist"" : ""Pink Floyd"",              ""year""   : 1973,              ""tracks"" : [                ""Speak To Me"",                ""Breathe"",                ""On The Run""              ]            }          }        ";        LoadAlbumData(json);    }    public static void LoadAlbumData(string json_text)    {        Console.WriteLine("Reading data from the following JSON string: {0}",                          json_text);        JsonData data = JsonMapper.ToObject(json_text);        // Dictionaries are accessed like a hash-table        Console.WriteLine("Album's name: {0}", data["album"]["name"]);        // Scalar elements stored in a JsonData instance can be cast to        // their natural types        string artist = (string) data["album"]["artist"];        int    year   = (int) data["album"]["year"];        Console.WriteLine("Recorded by {0} in {1}", artist, year);        // Arrays are accessed like regular lists as well        Console.WriteLine("First track: {0}", data["album"]["tracks"][0]);    }}

Output from the example:

Reading data from the following JSON string:          {            "album" : {              "name"   : "The Dark Side of the Moon",              "artist" : "Pink Floyd",              "year"   : 1973,              "tracks" : [                "Speak To Me",                "Breathe",                "On The Run"              ]            }          }Album's name: The Dark Side of the MoonRecorded by Pink Floyd in 1973First track: Speak To Me

Readers and Writers

An alternative interface to handling JSON data that might be familiar to some developers is through classes that make it possible to read and write data in a stream-like fashion. These classes are JsonReader and JsonWriter.

These two types are in fact the foundation of this library, and the JsonMapper type is built on top of them, so in a way, the developer can think of the reader and writer classes as the low-level programming interface for LitJSON.

Using JsonReader

using LitJson;using System;public class DataReader{    public static void Main()    {        string sample = @"{            ""name""  : ""Bill"",            ""age""   : 32,            ""awake"" : true,            ""n""     : 1994.0226,            ""note""  : [ ""life"", ""is"", ""but"", ""a"", ""dream"" ]          }";        PrintJson(sample);    }    public static void PrintJson(string json)    {        JsonReader reader = new JsonReader(json);        Console.WriteLine ("{0,14} {1,10} {2,16}", "Token", "Value", "Type");        Console.WriteLine (new String ('-', 42));        // The Read() method returns false when there's nothing else to read        while (reader.Read()) {            string type = reader.Value != null ?                reader.Value.GetType().ToString() : "";            Console.WriteLine("{0,14} {1,10} {2,16}",                              reader.Token, reader.Value, type);        }    }}

This example would produce the following output:

         Token      Value             Type------------------------------------------   ObjectStart                              PropertyName       name    System.String        String       Bill    System.String  PropertyName        age    System.String           Int         32     System.Int32  PropertyName      awake    System.String       Boolean       True   System.Boolean  PropertyName          n    System.String        Double  1994.0226    System.Double  PropertyName       note    System.String    ArrayStart                                    String       life    System.String        String         is    System.String        String        but    System.String        String          a    System.String        String      dream    System.String      ArrayEnd                                 ObjectEnd                            

Using JsonWriter

The JsonWriter class is quite simple. Keep in mind that if you want to convert some arbitrary object into a JSON string, you’d normally just use JsonMapper.ToJson.

using LitJson;using System;using System.Text;public class DataWriter{    public static void Main()    {        StringBuilder sb = new StringBuilder();        JsonWriter writer = new JsonWriter(sb);        writer.WriteArrayStart();        writer.Write(1);        writer.Write(2);        writer.Write(3);        writer.WriteObjectStart();        writer.WritePropertyName("color");        writer.Write("blue");        writer.WriteObjectEnd();        writer.WriteArrayEnd();        Console.WriteLine(sb.ToString());    }}

Output from the example:

[1,2,3,{"color":"blue"}]

Configuring the library’s behaviour

JSON is a very concise data-interchange format; nothing more, nothing less. For this reason, handling data in JSON format inside a program may require a deliberate decision on your part regarding some little detail that goes beyond the scope of JSON’s specs.

Consider, for example, reading data from JSON strings where single-quotes are used to delimit strings, or Javascript-style comments are included as a form of documentation. Those things are not part of the JSON standard, but they are commonly used by some developers, so you may want to be forgiving or strict depending on the situation. Or what about if you want to convert a .Net object into a JSON string, but pretty-printed (using indentation)?

To declare the behaviour you want, you may change a few properties from your JsonReader and JsonWriter objects.

Configuration of JsonReader

using LitJson;using System;public class JsonReaderConfigExample{    public static void Main()    {        string json;        json = " /* these are some numbers */ [ 2, 3, 5, 7, 11 ] ";        TestReadingArray(json);        json = " [ \"hello\", 'world' ] ";        TestReadingArray(json);    }    static void TestReadingArray(string json_array)    {        JsonReader defaultReader, customReader;        defaultReader = new JsonReader(json_array);        customReader  = new JsonReader(json_array);        customReader.AllowComments            = false;        customReader.AllowSingleQuotedStrings = false;        ReadArray(defaultReader);        ReadArray(customReader);    }    static void ReadArray(JsonReader reader)    {        Console.WriteLine("Reading an array");        try {            JsonData data = JsonMapper.ToObject(reader);            foreach (JsonData elem in data)                Console.Write("  {0}", elem);            Console.WriteLine("  [end]");        }        catch (Exception e) {            Console.WriteLine("  Exception caught: {0}", e.Message);        }    }}

The output would be:

Reading an array  2  3  5  7  11  [end]Reading an array  Exception caught: Invalid character '/' in input stringReading an array  hello  world  [end]Reading an array  Exception caught: Invalid character ''' in input string

Configuration of JsonWriter

using LitJson;using System;public enum AnimalType{    Dog,    Cat,    Parrot}public class Animal{    public string     Name { get; set; }    public AnimalType Type { get; set; }    public int        Age  { get; set; }    public string[]   Toys { get; set; }}public class JsonWriterConfigExample{    public static void Main()    {        var dog = new Animal {            Name = "Noam Chompsky",            Type = AnimalType.Dog,            Age  = 3,            Toys = new string[] { "rubber bone", "tennis ball" }        };        var cat = new Animal {            Name = "Colonel Meow",            Type = AnimalType.Cat,            Age  = 5,            Toys = new string[] { "cardboard box" }        };        TestWritingAnimal(dog);        TestWritingAnimal(cat, 2);    }    static void TestWritingAnimal(Animal pet, int indentLevel = 0)    {        Console.WriteLine("\nConverting {0}'s data into JSON..", pet.Name);        JsonWriter writer1 = new JsonWriter(Console.Out);        JsonWriter writer2 = new JsonWriter(Console.Out);        writer2.PrettyPrint = true;        if (indentLevel != 0)            writer2.IndentValue = indentLevel;        Console.WriteLine("Default JSON string:");        JsonMapper.ToJson(pet, writer1);        Console.Write("\nPretty-printed:");        JsonMapper.ToJson(pet, writer2);        Console.WriteLine("");    }}

The output from this example is:

Converting Noam Chompsky's data into JSON..Default JSON string:{"Name":"Noam Chompsky","Type":0,"Age":3,"Toys":["rubber bone","tennis ball"]}Pretty-printed:{    "Name" : "Noam Chompsky",    "Type" : 0,    "Age"  : 3,    "Toys" : [        "rubber bone",        "tennis ball"    ]}Converting Colonel Meow's data into JSON..Default JSON string:{"Name":"Colonel Meow","Type":1,"Age":5,"Toys":["cardboard box"]}Pretty-printed:{  "Name" : "Colonel Meow",  "Type" : 1,  "Age"  : 5,  "Toys" : [    "cardboard box"  ]}