C# – Deserialize a JSON array to a list

When you’re working with a JSON array, you can deserialize it to a list like this:

using System.Collections.Generic;
using System.Text.Json;

var movieList = JsonSerializer.Deserialize<List<Movie>>(json);
Code language: C# (cs)

This deserializes all of the objects in the JSON array into a List<Movie>. You can use this list object like usual.

Note: All examples will use System.Collections.Generic and System.Text.Json. I’ll exclude the using statements for brevity.

Example – JSON array and code

Valid JSON is either an object (i.e. { }) or an array (i.e. [ ]). The following is an example of a JSON array that contains 10 movie objects:

[
	{"Title":"Interstellar","Year":2014,"BoxOffice":701.8,"Director":"Christopher Nolan"},
	{"Title":"Inception","Year":2010,"BoxOffice":836.8,"Director":"Christopher Nolan"},
	{"Title":"Avengers: Endgame","Year":2019,"BoxOffice":2798,"Director":"Russo Brothers"},
	{"Title":"The Social Network","Year":2010,"BoxOffice":224.9,"Director":"David Fincher"},
	{"Title":"Seven","Year":1995,"BoxOffice":327.3,"Director":"David Fincher"},
	{"Title":"Black Panther","Year":2018,"BoxOffice":1344,"Director":"Ryan Coogler"},
	{"Title":"Edge of Tomorrow","Year":2014,"BoxOffice":370.5,"Director":"Doug Liman"},
	{"Title":"Joker","Year":2019,"BoxOffice":333.7,"Director":"Todd Phillips"},
	{"Title":"Avengers: Infinity War","Year":2018,"BoxOffice":2048,"Director":"Russo Brothers"},
	{"Title":"Ford v Ferrari","Year":2019,"BoxOffice":225.5,"Director":"James Mangold"}
]Code language: JSON / JSON with Comments (json)

Here’s an example of deserializing this JSON array into a list of movie objects (List<Movie>) and then using the list:

using System.Text.Json;

var list = JsonSerializer.Deserialize<List<Movie>>(moviesJson);

Console.WriteLine($"There are {list.Count} movies");
Code language: C# (cs)

This outputs the following:

There are 10 moviesCode language: plaintext (plaintext)

Deserialize and yield one object at a time

Deserialize<IEnumerable<Movie>> is the same as Deserialize<List<Movie>>. In both cases, it’ll deserialize all objects in the JSON array into List<Movie> and hold all objects in memory at once.

If you want to deserialize and yield one object at a time, use DeserializeAsyncEnumerable(). To use this, pass in the JSON as a stream:

using var movieJsonStream = new MemoryStream(Encoding.UTF8.GetBytes(moviesJson));

await foreach(var movie in JsonSerializer.DeserializeAsyncEnumerable<Movie>(movieJsonStream))
{
    ProcessMovie(movie);
}
Code language: C# (cs)

Note: This example is converting a string into a MemoryStream. Try to use a stream directly when possible – such as reading a file as a stream, or reading the HTTP response stream.

Non-array collection of objects

Sometimes you’ll have to deal with collections of objects that are stored in a JSON object instead of in a JSON array. Here’s an example:

{
  "Interstellar": {
    "Year": 2014,
    "BoxOffice": 701.8,
    "Director": "Christopher Nolan"
  },
  "Inception": {
    "Year": 2010,
    "BoxOffice": 836.8,
    "Director": "Christopher Nolan"
  },
  "Black Panther": {
    "Year": 2018,
    "BoxOffice": 1344,
    "Director": "Ryan Coogler"
  }
}Code language: JSON / JSON with Comments (json)

This is a collection of movie objects, but it’s not a list. It’s a collection of key/value pairs. This can be deserialized into Dictionary<string, Movie>:

var movieMap = JsonSerializer.Deserialize<Dictionary<string, Movie>>(moviesJson);
Code language: C# (cs)

Keep it simple and deserialize to a class that matches the JSON structure. Add a new class to match the structure when necessary.

Newtonsoft example

Here’s how you deserialize to list with Newtonsoft (in case you aren’t using System.Text.Json):

using Newtonsoft.Json;

var movies = JsonConvert.DeserializeObject<List<Movie>>(moviesJson);

Console.WriteLine($"Average box office revenue = ${movies.Average(m => m.BoxOffice)} mil");
Code language: C# (cs)

Note: moviesJson is the movies JSON array from the Example – JSON array and code section.

This outputs:

Average box office revenue = $921.05 milCode language: plaintext (plaintext)