Partilhar via

Como ler JSON como objetos .NET (desserializar)

Este artigo mostra como usar o System.Text.Json namespace para desserializar a partir de JavaScript Object Notation (JSON). Se você estiver portando o código existente do Newtonsoft.Json, consulte Como migrar para o 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 string ou um ficheiro, 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 sincronamente ou assincronamente.

Gorjeta

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

Todas as propriedades JSON que não estão representadas em sua classe são ignoradas por padrão. Além disso, se quaisquer propriedades do tipo forem necessárias, mas não estiverem presentes na carga JSON, a desserialização falhará.

Exemplos

O exemplo a seguir 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 exemplo a seguir:

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 DeserializeAsync método:

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 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, consulte Padrões da Web para JsonSerializerOptions.

Você pode implementar conversores personalizados para fornecer funcionalidade que não é suportada pelos conversores internos.

Desserializar sem uma classe do framework .NET

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

  • Utilize o Utf8JsonReader diretamente.

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

    O DOM permite navegar até uma subseção de uma carga JSON e desserializar um único valor, um tipo personalizado ou uma matriz. Para obter informações sobre o JsonNode DOM, consulte Desserializar subseções de uma carga JSON. Para obter informações sobre o JsonDocument DOM, consulte Como pesquisar um JsonDocument e JsonElement para subelementos.

  • Use o Visual Studio 2022 para gerar automaticamente a classe de que você precisa:

    • Copie o JSON que você precisa desserializar.
    • Crie um arquivo de classe e exclua o código do modelo.
    • Escolha Edit>Paste Special>Paste JSON as Classes.

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

Desserializar a partir de UTF-8

Para desserializar a partir de UTF-8, utilize uma sobrecarga de JsonSerializer.Deserialize que aceita um ReadOnlySpan<byte> ou um Utf8JsonReader, conforme mostrado nos exemplos a seguir. Os exemplos assumem 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 IA para desserializar 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, então surpresas e erros são possíveis. Para obter mais informações, consulte Copilot FAQs.

Ver também