Compartilhar via

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 seguinte exemplo mostra como desserializar uma cadeia de caracteres JSON:

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}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

weatherForecast = JsonSerializer.Deserialize(Of WeatherForecastWithPOCOs)(jsonString)

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:

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:

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. Você pode personalizar o prompt para usar uma cadeia de caracteres JSON com nomes de propriedade e valores que atendam às suas necessidades.

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

Generate code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe","Age":30} to an equivalent .NET object.
Map property names & values.
Provide example output.

O GitHub Copilot é alimentado por IA, portanto é passível de surpresas e erros. Para obter mais informações, consulte Perguntas frequentes sobre o Copilot.

Consulte também