Como ler JSON como objetos .NET (desserializar)

Artigo
09/25/2024

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 cadeia de caracteres ou um arquivo, chame o JsonSerializer.Deserialize método. 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 forma síncrona ou assíncrona.

Gorjeta

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

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 no tipo forem necessárias , mas não estiverem presentes na carga JSON útil, 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:

Por padrão, a correspondência de nome de propriedade diferencia maiúsculas de minúsculas. Você pode especificar a indiferenciação de maiúsculas e minúsculas.
Construtores não públicos são ignorados pelo serializador.
A desserialização para objetos imutáveis ou propriedades que não têm acessadores públicos set é suportada, mas não habilitada por padrão. Consulte Tipos e registros imutáveis.
Por padrão, enums são suportados como números. Você pode desserializar campos de enum 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 lançam 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, 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 .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:

Use 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 útil. Para obter informações sobre o JsonDocument DOM, consulte Como pesquisar subelementos JsonDocument e JsonElement.
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, chame uma JsonSerializer.Deserialize sobrecarga que leva 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 o Copilot do GitHub para desserializar JSON

Você pode usar o GitHub Copilot em seu IDE para gerar código que usa System.Text.Json para desserializar a partir de JSON.

Se você estiver usando o Visual Studio 2022 versão 17.8 ou posterior, poderá tentar o Copilot GitHub controlado por IA no Visual Studio para gerar código que usa System.Text.Json para desserializar JSON. Envie sua pergunta como um prompt na janela de bate-papo do Copilot, como no exemplo a seguir. Você também pode enviar prompts usando o bate-papo embutido na própria janela do editor.

Nota

O GitHub Copilot é alimentado por IA, então surpresas e erros são possíveis. Certifique-se de verificar qualquer código gerado ou sugestões. Para obter mais informações sobre o uso geral do GitHub Copilot, impacto no produto, supervisão humana e privacidade, consulte Perguntas frequentes sobre o GitHub Copilot.

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

Gere código a ser usado System.Text.Json para desserializar uma cadeia de caracteres JSON {"FirstName":"John","LastName":"Doe","Age":30} para um objeto .NET equivalente. Mapeie nomes de propriedades & valores. Forneça um exemplo de saída.

Você pode personalizar o prompt para usar uma cadeia de caracteres JSON com nomes de propriedade e valores que atendam às suas necessidades.

Você pode usar recursos de bate-papo, como comandos de barra, referências a arquivos, métodos ou classes e threads, para definir a intenção e obter melhores respostas com contexto de escopo. Para uma classe existente em um projeto aberto no IDE, você pode solicitar o Copiloto do GitHub com /generate code to dserialize JSON to equivalent .NET object in #Filename.

A saída a seguir mostra um exemplo de resposta do Copilot Chat:

Here's an example of how you can use `System.Text.Json` to deserialize a JSON string into a .NET object in C#:

using System;
using System.Text.Json;
public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}
public class Program
{
    public static void Main()
    {
        string jsonString = "{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"Age\":30}";
        Person person = JsonSerializer.Deserialize<Person>(jsonString);
        Console.WriteLine($"FirstName: {person.FirstName}");
        Console.WriteLine($"LastName: {person.LastName}");
        Console.WriteLine($"Age: {person.Age}");
    }
}

**Example Output**
FirstName: John
LastName: Doe
Age: 30

This code defines a Person class with properties that match the JSON string. It then uses `JsonSerializer.Deserialize` to convert the JSON string into a `Person` object and prints the properties to the console.

Quando o Copilot retorna um bloco de código, a resposta inclui opções para copiar o código, inserir o código em um novo arquivo ou visualizar a saída do código.

Nota

Seus resultados podem ser diferentes do que é mostrado nas respostas de exemplo. Os modelos de IA não são determinísticos, o que significa que podem retornar respostas diferentes quando feitas a mesma pergunta. Isso pode ser devido a aprendizado e adaptação adicionais ao longo do tempo, variação de idioma, mudanças no contexto, como seu histórico de bate-papo, e muito mais.

Para obter mais informações, consulte:

Partilhar via