JContainer, JObject, JToken and Linq confusion

Question

I am having trouble understanding when to use JContainer, JObject, and JToken. I understand from the "standards" that JObject is composed of JProperties and that JToken is the base abstract class for all of the JToken types, but I don't understand JContainer.

I am using C# and I just bought LinqPad Pro 5.

I have a JSON data source in a file, so I'm deserializing that file's contents successfully using this statement:

string json;
using (StreamReader reader = new StreamReader(@"myjsonfile.json"))
{
    json = reader.ReadToEnd();
}

At that point, I take the JSON string object and deserialize it to a JObject (and this might be my mistake--perhaps I need to make jsonWork a JToken or JContainer?):

JObject jsonWork = (JObject)JsonConvert.DeserializeObject(json);

In my JSON data (the string represented by JSON), I have three objects--the top-level object look similar to this:

{
  "Object1" : { ... },
  "Object2" : { ... },
  "Object3" : { ... }
}

Each object is composed of all sorts of tokens (arrays, strings, other objects, etc.), so it is dynamic JSON. (I used ellipses as placeholders rather than muddying up this question wit lots of JSON data.)

I want to process "Object1", "Object2", and "Object3" separately using LINQ, however. So, ideally, I would like something like this:

// these lines DO NOT work    
var jsonObject1 = jsonWork.Children()["Object1"]
var jsonObject2 = jsonWork.Children()["Object2"]
var jsonObject3 = jsonWork.Children()["Object3"]

But the above lines fail.

I used var above because I have no idea what object type I should be using: JContainer, JObject, or JToken! Just so you know what I want to do, once the above jsonObject# variables are properly assigned, I would like to use LINQ to query the JSON they contain. Here is a very simple example:

var query = from p in jsonObject1
   where p.Name == "Name1"
   select p

Of course, my LINQ ultimately will filter for JSON arrays, objects, strings, etc., in the jsonObject variable. I think once I get going, I can use LinqPad to help me filter the JSON using LINQ.

I discovered that if I use:

// this line WORKS 
var jsonObject1 = ((JObject)jsonWork).["Object1"];

Then I get an JObject type in jsonObject1. Is this the correct approach?

It is unclear to me when/why one would use JContainer when it seems that JToken and JObject objects work with LINQ quite well. What is the purpose of JContainer?

Answer 1

You don't really need to worry about JContainer in most cases. It is there to help organize and structure LINQ-to-JSON into well-factored code.

The JToken hierarchy looks like this:

JToken             - abstract base class     
   JContainer      - abstract base class of JTokens that can contain other JTokens
       JArray      - represents a JSON array (contains an ordered list of JTokens)
       JObject     - represents a JSON object (contains a collection of JProperties)
       JProperty   - represents a JSON property (a name/JToken pair inside a JObject)
   JValue          - represents a primitive JSON value (string, number, boolean, null)

So you see, a JObject is a JContainer, which is a JToken.

Here's the basic rule of thumb:

• If you know you have an object (denoted by curly braces { and } in JSON), use JObject
• If you know you have an array or list (denoted by square brackets [ and ]), use JArray
• If you know you have a primitive value, use JValue
• If you don't know what kind of token you have, or want to be able to handle any of the above in a general way, use JToken. You can then check its Type property to determine what kind of token it is and cast it appropriately.