Serialización y deserialización de JSON en .NET: información general
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:
- Atributos del espacio de nombres System.Runtime.Serialization.
- Atributo System.SerializableAttribute y la interfaz ISerializable. Estos tipos solo se usan solo para la serialización binaria y XML.
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.
