Como ler JSON como objetos .NET (desserializar)

Este artigo mostra como usar o namespace System.Text.Json para desserializar da JSON (JavaScript Object Notation). Se você estiver portando o código existente de Newtonsoft.Json, confira Como migrar para System.Text.Json.

Uma maneira comum de desserializar JSON é ter (ou criar) uma classe .NET com propriedades e campos que representam uma ou mais das propriedades JSON. Em seguida, para desserializar de uma cadeia de caracteres ou um arquivo, chame o método JsonSerializer.Deserialize. Para as sobrecargas genéricas, o parâmetro de tipo genérico é a classe .NET. Para as sobrecargas não genéricas, você passa o tipo da classe como um parâmetro de método. Você pode desserializar de maneira síncrona ou assíncrona.

Dica

Você pode usar a assistência de IA para desserializar uma cadeia de caracteres JSON.

Todas as propriedades JSON que não são representadas na sua classe são ignoradas por padrão. Além disso, se alguma propriedade no tipo for necessária, mas não estiver presente no conteúdo JSON, a desserialização falhará.

Exemplos

O exemplo a seguir mostra como desserializar uma cadeia de caracteres JSON que contém coleções e objetos aninhados:

using System.Text.Json;

namespace DeserializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string jsonString =
                """
                {
                  "Date": "2019-08-01T00:00:00-07:00",
                  "TemperatureCelsius": 25,
                  "Summary": "Hot",
                  "DatesAvailable": [
                    "2019-08-01T00:00:00-07:00",
                    "2019-08-02T00:00:00-07:00"
                  ],
                  "TemperatureRanges": {
                    "Cold": {
                      "High": 20,
                      "Low": -10
                    },
                    "Hot": {
                      "High": 60,
                      "Low": 20
                    }
                  },
                  "SummaryWords": [
                    "Cool",
                    "Windy",
                    "Humid"
                  ]
                }
                """;
                
            WeatherForecast? weatherForecast = 
                JsonSerializer.Deserialize<WeatherForecast>(jsonString);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");

            if (weatherForecast?.DatesAvailable != null)
            {
                foreach (DateTimeOffset dateTimeOffset in weatherForecast.DatesAvailable)
                {
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}");
                }
            }

            if (weatherForecast?.TemperatureRanges != null)
            {
                foreach (KeyValuePair<string, HighLowTemps> temperatureRange in weatherForecast.TemperatureRanges)
                {
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}");
                }
            }

            if (weatherForecast?.SummaryWords != null)
            {
                foreach (string summaryWord in weatherForecast.SummaryWords)
                {
                    Console.WriteLine($"SummaryWord: {summaryWord}");
                }
            }
        }
    }
}

/* Output:
 * 
 * Date: 8/1/2019 12:00:00 AM -07:00
 * TemperatureCelsius: 25
 * Summary: Hot
 * DateAvailable: 8/1/2019 12:00:00 AM -07:00
 * DateAvailable: 8/2/2019 12:00:00 AM -07:00
 * TemperatureRange: Cold is -10 to 20
 * TemperatureRange: Hot is 20 to 60
 * SummaryWord: Cool
 * SummaryWord: Windy
 * SummaryWord: Humid
 * */

Imports System.Text.Json

Namespace DeserializeExtra

    Public Class WeatherForecast
        Public Property [Date] As DateTimeOffset
        Public Property TemperatureCelsius As Integer
        Public Property Summary As String
        Public SummaryField As String
        Public Property DatesAvailable As IList(Of DateTimeOffset)
        Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
        Public Property SummaryWords As String()
    End Class

    Public Class HighLowTemps
        Public Property High As Integer
        Public Property Low As Integer
    End Class

    Public NotInheritable Class Program

        Public Shared Sub Run()
            Dim jsonString As String =
                "{
                  ""Date"": ""2019-08-01T00:00:00-07:00"",
                  ""TemperatureCelsius"": 25,
                  ""Summary"": ""Hot"",
                  ""DatesAvailable"": [
                    ""2019-08-01T00:00:00-07:00"",
                    ""2019-08-02T00:00:00-07:00""
                  ],
                  ""TemperatureRanges"": {
                    ""Cold"": {
                      ""High"": 20,
                      ""Low"": -10
                    },
                    ""Hot"": {
                      ""High"": 60,
                      ""Low"": 20
                    }
                  },
                  ""SummaryWords"": [
                    ""Cool"",
                    ""Windy"",
                    ""Humid""
                  ]
                }"

            Dim weatherForecast As WeatherForecast =
                JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

            Console.WriteLine($"Date: {weatherForecast?.Date}")
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}")
            Console.WriteLine($"Summary: {weatherForecast?.Summary}")

            If weatherForecast?.DatesAvailable IsNot Nothing Then
                For Each dateTimeOffset As DateTimeOffset In weatherForecast.DatesAvailable
                    Console.WriteLine($"DateAvailable: {dateTimeOffset}")
                Next
            End If

            If weatherForecast?.TemperatureRanges IsNot Nothing Then
                For Each temperatureRange As KeyValuePair(Of String, HighLowTemps) In weatherForecast.TemperatureRanges
                    Console.WriteLine($"TemperatureRange: {temperatureRange.Key} is {temperatureRange.Value.Low} to {temperatureRange.Value.High}")
                Next
            End If

            If weatherForecast?.SummaryWords IsNot Nothing Then
                For Each summaryWord As String In weatherForecast.SummaryWords
                    Console.WriteLine($"SummaryWord: {summaryWord}")
                Next
            End If
        End Sub

    End Class

End Namespace

' Output:
'
'Date: 8/1/2019 12:00:00 AM -07:00
'TemperatureCelsius: 25
'Summary: Hot
'DateAvailable: 8/1/2019 12:00:00 AM -07:00
'DateAvailable: 8/2/2019 12:00:00 AM -07:00
'TemperatureRange: Cold is -10 to 20
'TemperatureRange: Hot is 20 to 60
'SummaryWord: Cool
'SummaryWord: Windy
'SummaryWord: Humid

Para desserializar de um arquivo usando código síncrono, leia o arquivo em uma cadeia de caracteres, conforme mostrado no seguinte exemplo:

using System.Text.Json;

namespace DeserializeFromFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            string fileName = "WeatherForecast.json";
            string jsonString = File.ReadAllText(fileName);
            WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString)!;

            Console.WriteLine($"Date: {weatherForecast.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

jsonString = File.ReadAllText(fileName)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

Para desserializar de um arquivo usando código assíncrono, chame o método DeserializeAsync:

using System.Text.Json;

namespace DeserializeFromFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            string fileName = "WeatherForecast.json";
            using FileStream openStream = File.OpenRead(fileName);
            WeatherForecast? weatherForecast = 
                await JsonSerializer.DeserializeAsync<WeatherForecast>(openStream);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

Dim openStream As FileStream = File.OpenRead(fileName)
weatherForecast1 = Await JsonSerializer.DeserializeAsync(Of WeatherForecast)(openStream)

Comportamento de desserialização

Os seguintes comportamentos se aplicam ao desserializar o JSON:

• Por padrão, a correspondência de nome de propriedade diferencia maiúsculas de minúsculas. Você pode especificar não diferenciar maiúsculas de minúsculas.
• Construtores não públicos são ignorados pelo serializador.
• A desserialização para objetos ou propriedades imutáveis que não têm acessadores públicos set tem suporte, mas não está habilitada por padrão. Confira Tipos imutáveis e registros.
• Por padrão, há suporte para enumerações como números. Você pode desserializar campos de enumeração de cadeia de caracteres.
• Por padrão, os campos são ignorados. Você pode incluir campos.
• Por padrão, comentários ou vírgulas à direita no JSON geram exceções. Você pode permitir comentários e vírgulas à direita.
• A profundidade máxima padrão é 64.

Quando você usa System.Text.Json indiretamente em um aplicativo ASP.NET Core, alguns comportamentos padrão são diferentes. Para obter mais informações, confira Padrões da Web para JsonSerializerOptions.

Você pode implementar conversores personalizados para fornecer funcionalidades que não são compatíveis com os conversores internos.

Desserializar sem uma classe .NET

Se você tiver o JSON no qual deseja desserializar e não tiver a classe para desserializá-lo, terá opções diferentes de criar manualmente a classe de que precisa:

• Use o Utf8JsonReader diretamente.

• Desserialize em um DOM JSON (modelo de objeto do documento) e extraia o que você precisa do DOM.

  O DOM permite que você navegue até uma subseção de um conteúdo JSON e desserialize um só valor, um tipo personalizado ou uma matriz. Para informações sobre o JsonNode DOM, confira Desserializar subseções de um conteúdo JSON. Para informações sobre o DOM JsonDocument, confira Como pesquisar um JsonDocument e JsonElement em busca de subconjuntos.

• Use o Visual Studio 2022 ou posterior para gerar automaticamente a classe necessária:

  • Copie o JSON de que você precisa para desserializar.
  • Crie um arquivo de classe e exclua o código do modelo.
  • Escolha Editar>Colar especial>Colar JSON como Classes.

  O resultado é uma classe que você pode usar para seu destino de desserialização.

Desserializar de UTF-8

Para desserializar de UTF-8, chame uma sobrecarga JsonSerializer.Deserialize que usa um ReadOnlySpan<byte> ou um Utf8JsonReader, conforme mostrado nos exemplos a seguir. Os exemplos pressupõem que o JSON está em uma matriz de bytes chamada jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan)!;

Dim jsonString = Encoding.UTF8.GetString(jsonUtf8Bytes)
weatherForecast1 = JsonSerializer.Deserialize(Of WeatherForecast)(jsonString)

var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader)!;

' This code example doesn't apply to Visual Basic. For more information, go to the following URL:
' https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to#visual-basic-support

Usar a IA para desserializar o JSON

Você pode usar ferramentas de IA, como o GitHub Copilot, para gerar código que usa System.Text.Json para desserializar do JSON. Por exemplo, você pode personalizar o prompt para demonstrar a desserialização quando a classe de destino define uma propriedade ausente da entrada JSON.

O texto a seguir mostra um exemplo de prompt para o Copilot Chat:

Generate C# code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe"} to an equivalent .NET object, where the class defines an Age property.
Show what happens when the JSON is missing a property defined in the class.
Provide example output.

Examine as sugestões do Copilot antes de aplicá-las.

Para obter mais informações sobre o GitHub Copilot, consulte as perguntas frequentes do GitHub.

Consulte também

• Como desserializar para uma interface
• GitHub Copilot no Visual Studio
• GitHub Copilot no Visual Studio Code