Como ler JSON como objetos .NET (desserializar)

Artigo
09/27/2024

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 string JSON com GitHub Copilot.

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:

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 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

Use o GitHub Copilot para desserializar JSON

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

Se você estiver usando o Visual Studio 2022 versão 17.8 ou posterior, poderá experimentar o GitHub Copilot no Visual Studio orientado por IA 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 em linha na própria janela do editor.

Observação

O GitHub Copilot é alimentado por IA, portanto é passível de surpresas e erros. Verifique qualquer código gerado ou sugestões. Para obter mais informações sobre o uso geral do GitHub Copilot, o impacto do produto, a supervisão humana e a privacidade, consulte Perguntas frequentes sobre o GitHub Copilot.

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

Gere o 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 & valores de propriedades. 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 o contexto com escopo. Para uma classe existente em um projeto que está aberto no IDE, você pode solicitar o GitHub Copilot 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.

Observação

Seus resultados podem ser diferentes do que é mostrado nas respostas de exemplo. Os modelos de IA não são determinísticos, ou seja, eles podem retornar respostas diferentes quando fazem 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 saber mais, veja:

Central de Confiabilidade do GitHub Copilot
GitHub Copilot no Visual Studio
GitHub Copilot no VS Code

Compartilhar via