Serialización y deserialización de JSON en .NET: información general

  • Artículo

El espacio de nombres System.Text.Json proporciona funcionalidad para serializar y deserializar desde JSON (notaciones de objetos JavaScript). La serialización es el proceso de convertir el estado de un objeto, es decir, los valores de sus propiedades, en un formulario que se puede almacenar o transmitir. El formulario serializado no incluye información sobre los métodos asociados de un objeto. La deserialización reconstruye un objeto a partir del formulario serializado.

El diseño de biblioteca System.Text.Json resalta el alto rendimiento y la asignación de memoria baja en un amplio conjunto de características. La compatibilidad integrada con UTF-8 optimiza el proceso de lectura y escritura de texto JSON codificado como UTF-8, que es la codificación más frecuente de los datos en Internet y los archivos en disco.

La biblioteca también proporciona clases para trabajar con un modelo de objetos de documento (DOM) en memoria. Esta característica permite el acceso aleatorio a los elementos de una cadena o archivo JSON.

Para Visual Basic, hay algunas limitaciones en las partes de la biblioteca que puede usar. Para más información, consulte Soporte técnico de Visual Basic.

Cómo obtener la biblioteca

La biblioteca está integrada como parte del marco compartido para .NET Core 3.0 y versiones posteriores. La característica de generación de origen está integrada como parte del marco compartido para .NET 6 y versiones posteriores.

En las versiones del marco anteriores a .NET Core 3.0, instale el paquete NuGet System.Text.Json. que admite lo siguiente:

  • .NET Standard 2.0 y versiones posteriores
  • .NET Framework 4.6.2 y versiones posteriores
  • .NET Core 2.1 y versiones posteriores
  • .NET 5 y versiones posteriores

Espacios de nombres y API

  • El espacio de nombres System.Text.Json contiene todos los puntos de entrada y los tipos principales.
  • El espacio de nombres System.Text.Json.Serialization contiene atributos e interfaces API para escenarios avanzados y personalización específicos de la serialización y deserialización.

Los ejemplos de código que se muestran en este artículo requieren directivas using para uno o ambos espacios de nombres.

Importante

System.Text.Json no admite las siguientes API de serialización que podría haber usado anteriormente:

Métodos de extensión HttpClient y HttpContent

La serialización y deserialización de cargas JSON de la red son operaciones comunes. Los métodos de extensión de HttpClient y HttpContent permiten realizar estas operaciones en una sola línea de código. Estos métodos de extensión usan valores predeterminados web para JsonSerializerOptions.

En el siguiente ejemplo se muestra el uso de HttpClientJsonExtensions.GetFromJsonAsync y HttpClientJsonExtensions.PostAsJsonAsync:

using System.Net.Http.Json;

namespace HttpClientExtensionMethods
{
    public class User
    {
        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Username { get; set; }
        public string? Email { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            using HttpClient client = new()
            {
                BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
            };

            // Get the user information.
            User? user = await client.GetFromJsonAsync<User>("users/1");
            Console.WriteLine($"Id: {user?.Id}");
            Console.WriteLine($"Name: {user?.Name}");
            Console.WriteLine($"Username: {user?.Username}");
            Console.WriteLine($"Email: {user?.Email}");

            // Post a new user.
            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
            Console.WriteLine(
                $"{(response.IsSuccessStatusCode ? "Success" : "Error")} - {response.StatusCode}");
        }
    }
}

// Produces output like the following example but with different names:
//
//Id: 1
//Name: Tyler King
//Username: Tyler
//Email: Tyler @contoso.com
//Success - Created

Imports System.Net.Http
Imports System.Net.Http.Json

Namespace HttpClientExtensionMethods

    Public Class User
        Public Property Id As Integer
        Public Property Name As String
        Public Property Username As String
        Public Property Email As String
    End Class

    Public Class Program

        Public Shared Async Function Main() As Task
            Using client As New HttpClient With {
                .BaseAddress = New Uri("https://jsonplaceholder.typicode.com")
                }

                ' Get the user information.
                Dim user1 As User = Await client.GetFromJsonAsync(Of User)("users/1")
                Console.WriteLine($"Id: {user1.Id}")
                Console.WriteLine($"Name: {user1.Name}")
                Console.WriteLine($"Username: {user1.Username}")
                Console.WriteLine($"Email: {user1.Email}")

                ' Post a new user.
                Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("users", user1)
                Console.WriteLine(
                $"{(If(response.IsSuccessStatusCode, "Success", "Error"))} - {response.StatusCode}")
            End Using
        End Function

    End Class

End Namespace

' Produces output like the following example but with different names:
'
'Id: 1
'Name: Tyler King
'Username: Tyler
'Email: Tyler @contoso.com
'Success - Created

También hay métodos de extensión para System.Text.Json en HttpContent.

Reflexión frente a generación de origen

De manera predeterminada, System.Text.Json recopila los metadatos que necesita para acceder a las propiedades de los objetos para la serialización y la deserialización en tiempo de ejecución mediante la reflexión. Como alternativa, System.Text.Json puede usar la característica de generación de origen de C# para mejorar el rendimiento, reducir el uso de memoria privada y facilitar el recorte de ensamblados, lo que reduce el tamaño de la aplicación.

Para obtener más información, consulte Reflexión frente a generación de código fuente.

Información de seguridad

Para obtener información sobre las amenazas de seguridad que se tuvieron en cuenta al diseñar JsonSerializer y cómo se pueden mitigar, vea Modelo de amenazas de System.Text.Json.

Seguridad para subprocesos

El serializador System.Text.Json se diseñó teniendo en cuenta la seguridad de subprocesos. Prácticamente, esto significa que una vez bloqueadas, las instancias JsonSerializerOptions se pueden compartir de forma segura entre varios subprocesos. JsonDocument proporciona una representación DOM inmutable y, en .NET 8 y versiones posteriores, la representación DOM segura para subprocesos para los valores JSON.

Recursos adicionales