Lectura de JSON como objetos .NET (deserializar)

Artículo
09/30/2024

En este artículo se muestra cómo usar el espacio de nombres System.Text.Json para deserializar desde la notación de objetos JavaScript (JSON). Si va a portar el código existente de Newtonsoft.Json, consulte Procedimiento para migrar a System.Text.Json.

Una manera común de deserializar JSON es tener (o crear) una clase .NET con propiedades y campos que representan una o varias de las propiedades JSON. Posteriormente, para deserializar a partir de una cadena o un archivo, llame al método JsonSerializer.Deserialize. Para las sobrecargas genéricas, el parámetro de tipo genérico es la clase .NET. Para las sobrecargas no genéricas, se pasa el tipo de la clase como parámetro de método. Se puede deserializar de forma sincrónica o asincrónica.

Sugerencia

Puede usar la asistencia de IA para deserializar una cadena JSON con GitHub Copilot.

Se omiten de forma predeterminada todas las propiedades JSON que no están representadas en la clase. Además, si se requieren propiedades en el tipo, pero no están presentes en la carga JSON, se producirá un error en la deserialización.

Ejemplos

En el ejemplo siguiente se muestra cómo deserializar una cadena 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 deserializar a partir de un archivo mediante código sincrónico, lea el archivo en una cadena, tal y como se muestra en el ejemplo siguiente:

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 deserializar a partir de un archivo mediante código asincrónico, llame al 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)

Comportamiento de la deserialización

Al deserializar JSON se aplican los comportamientos siguientes:

De forma predeterminada, la coincidencia de nombres de la propiedad distingue mayúsculas de minúsculas. Puede especificar la no distinción de mayúsculas y minúsculas.
El serializador omite los constructores que no son públicos.
Se admite la deserialización a objetos inmutables o propiedades que no tienen descriptores de acceso públicos set, pero que no están habilitados de forma predeterminada. Consulte Tipos y registros inmutables.
De forma predeterminada, las enumeraciones se admiten como números. Puede deserializar campos de enumeración de cadena.
De forma predeterminada, se omiten los campos. Puede incluir campos.
De forma predeterminada, los comentarios o las comas finales en el JSON inician excepciones. Puede permitir comentarios y comas finales.
La profundidad máxima predeterminada es 64.

Cuando se usa System.Text.Json indirectamente en una aplicación ASP.NET Core, algunos comportamientos predeterminados son diferentes. Para obtener más información, vea Valores predeterminados web para JsonSerializerOptions.

Puede implementar convertidores personalizados para proporcionar funcionalidad que no admiten los convertidores integrados.

Deserializar sin una clase .NET

Si tiene un archivo JSON que desea deserializar y no tiene la clase en la que deserializarlo, además de crear manualmente la clase que necesita, tiene otras opciones:

Use Utf8JsonReader directamente.
Deserialice en un DOM (Document Object Model) de JSON y extraiga lo que necesita de DOM.

DOM le permite navegar a una subsección de una carga JSON y deserializar un valor único, un tipo personalizado o una matriz. Para obtener más información sobre DOM de JsonNode, consulte Deserializar subsecciones de una carga JSON. Para obtener más información sobre DOM de JsonDocument, consulte Cómo buscar subelementos en JsonDocument y JsonElement.
Use Visual Studio 2022 para generar automáticamente la clase que necesita:
- Copie el JSON que necesita para deserializar.
- Cree un archivo de clase y elimine el código de plantilla.
- Seleccione Editar>Pegado especial>Pegar JSON como clases.
El resultado es una clase que puede usar para el destino de deserialización.

Deserialización desde UTF-8

Para deserializar desde UTF-8, llame a una sobrecarga JsonSerializer.Deserialize que tome un valor ReadOnlySpan<byte> o Utf8JsonReader, tal y como se muestra en el ejemplo siguiente. En los ejemplos se presupone que el JSON está en una matriz de bytes denominada 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 GitHub Copilot para deserializar en JSON

Puede usar GitHub Copilot en el IDE para generar código que use System.Text.Json para deserializar de JSON.

Si usa Visual Studio 2022, versión 17.8 o posterior, puede probar GitHub Copilot controlado por IA en Visual Studio para generar código que use System.Text.Json para deserializar en JSON. Envíe su pregunta como solicitud en la ventana de chat de Copilot, como en el ejemplo siguiente. También puede enviar mensajes mediante el chat en línea en la propia ventana del editor.

Nota:

GitHub Copilot funciona con IA, por lo que es posible que se produzcan sorpresas y errores. Asegúrese de comprobar cualquier código o sugerencia generado. Para obtener más información sobre el uso general de GitHub Copilot, impacto en el producto, supervisión humana y privacidad, consulte Preguntas más frecuentes sobre GitHub Copilot.

En el texto siguiente se muestra un mensaje de ejemplo para Copilot Chat:

Genere código que se usará System.Text.Json para deserializar una cadena JSON {"FirstName":"John","LastName":"Doe","Age":30} en un objeto .NET equivalente. Asigne nombres y valores de propiedad. Proporcione una salida de ejemplo.

Puede personalizar la solicitud para usar una cadena JSON con nombres y valores de propiedad que se adapten a sus requisitos.

Puede usar características de chat, como comandos de barra diagonal, referencias a archivos, métodos, clases y subprocesos, para establecer la intención y obtener mejores respuestas con contexto con ámbito. Para una clase existente en un proyecto abierto en el IDE, puede solicitar GitHub Copilot con /generate code to dserialize JSON to equivalent .NET object in #Filename

En la salida siguiente se muestra un ejemplo de respuesta de 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.

Cuando Copilot devuelve un bloque de código, la respuesta incluye opciones para copiar el código, insertar el código en un nuevo archivo u obtener una vista previa de la salida del código.

Nota:

Los resultados pueden ser diferentes de lo que se muestra en las respuestas de ejemplo. Los modelos de IA no son deterministas, lo que significa que pueden devolver respuestas diferentes cuando se le haga la misma pregunta. Esto puede deberse al aprendizaje y la adaptación adicionales a lo largo del tiempo, la variación del lenguaje, los cambios en el contexto, como el historial de chat, etc.

Para más información, vea:

Compartir a través de