Compartir a través de

Lectura de JSON como objetos .NET (deserializar)

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.

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:

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:

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

Uso de IA para deserializar JSON

Puede usar herramientas de inteligencia artificial, como GitHub Copilot, para generar código que usa System.Text.Json para deserializar desde JSON. Puede personalizar la solicitud para usar una cadena JSON con nombres y valores de propiedad que se adapten a sus requisitos.

En el texto siguiente se muestra un mensaje de ejemplo para 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.

GitHub Copilot funciona con IA, por lo que es posible que se produzcan sorpresas y errores. Para obtener más información, consulte Preguntas más frecuentes sobre Copilot.

Consulte también