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 movies
Code 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 mil
Code language: plaintext (plaintext)

6 thoughts on “C# – Deserialize a JSON array to a list”

  1. Hello,

    Could you explain what the moviesJson is in
    var movies = JsonConvert.DeserializeObject<List>(moviesJson);

    Thank you!

  2. Having a small issue.
    The deserialize works as expected and the is filled with the ten movies but if I try and drill into the Movie object they are all null.

    Could you also post the .Net classes you used

    • I’d guess it’s either 1) non-public setters or 2) property name casing mismatch. Both of these would cause that.

      Here’s the movie class I used:

      public class Movie
          public string Title { get; set; }
          public int Year { get; set; }
          public decimal BoxOffice { get; set; }
          public string Director { get; set; }


Leave a Comment