Partilhar via

Serialização e desserialização JSON (empacotamento e desempacotamento) no .NET - visão geral

  • Artigo

O System.Text.Json namespace fornece funcionalidade para serializar e desserializar a partir de JavaScript Object Notation (JSON). Serialização é o processo de converter o estado de um objeto, ou seja, os valores de suas propriedades, em uma forma que pode ser armazenada ou transmitida. O formulário serializado não inclui nenhuma informação sobre os métodos associados de um objeto. A desserialização reconstrói um objeto a partir do formulário serializado.

O design da System.Text.Json biblioteca enfatiza o alto desempenho e a baixa alocação de memória em um extenso conjunto de recursos. O suporte UTF-8 integrado otimiza o processo de leitura e gravação de texto JSON codificado como UTF-8, que é a codificação mais prevalente para dados na Web e arquivos no disco.

A biblioteca também fornece classes para trabalhar com um modelo de objeto de documento (DOM) na memória. Esse recurso permite o acesso aleatório aos elementos em um arquivo JSON ou cadeia de caracteres.

Para o Visual Basic, há algumas limitações sobre quais partes da biblioteca você pode usar. Para obter mais informações, consulte Suporte do Visual Basic.

Como obter a biblioteca

A biblioteca é interna como parte da estrutura compartilhada para .NET Core 3.0 e versões posteriores. O recurso de geração de origem é interno como parte da estrutura compartilhada para .NET 6 e versões posteriores.

Para versões de estrutura anteriores ao .NET Core 3.0, instale o System.Text.Json pacote NuGet. O pacote suporta:

  • .NET Standard 2.0 e posterior
  • .NET Framework 4.6.2 e posterior
  • .NET Core 2.1 e posterior
  • .NET 5 e posterior

Namespaces e APIs

  • O System.Text.Json namespace contém todos os pontos de entrada e os tipos principais.
  • O System.Text.Json.Serialization namespace contém atributos e APIs para cenários avançados e personalização específica para serialização e desserialização.

Os exemplos de código mostrados neste artigo exigem using diretivas para um ou ambos esses namespaces.

Importante

System.Text.Json não suporta as seguintes APIs de serialização que você pode ter usado anteriormente:

Métodos de extensão HttpClient e HttpContent

Serializar e desserializar cargas úteis JSON da rede são operações comuns. Os métodos de extensão em HttpClient e HttpContent permitem que você faça essas operações em uma única linha de código. Esses métodos de extensão usam padrões da Web para JsonSerializerOptions.

O exemplo a seguir ilustra o uso de HttpClientJsonExtensions.GetFromJsonAsync e 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

Há também métodos de extensão para System.Text.Json em HttpContent.

Reflexão vs. geração de fontes

Por padrão, System.Text.Json reúne os metadados necessários para acessar propriedades de objetos para serialização e desserialização em tempo de execução usando reflexão. Como alternativa, System.Text.Json pode usar o recurso de geração de código-fonte C# para melhorar o desempenho, reduzir o uso de memória privada e facilitar o corte de montagem, o que reduz o tamanho do aplicativo.

Para obter mais informações, consulte Reflexão versus geração de origem.

Informações de segurança

Para obter informações sobre ameaças à segurança que foram consideradas ao projetar JsonSerializere como elas podem ser atenuadas, consulte System.Text.Json Modelo de ameaça.

Segurança de roscas

O System.Text.Json serializador foi projetado com a segurança do thread em mente. Na prática, isso significa que, uma vez bloqueadas, JsonSerializerOptions as instâncias podem ser compartilhadas com segurança em vários threads. JsonDocument fornece uma representação DOM imutável e, no .NET 8 e versões posteriores, thread-safe, para valores JSON.

Recursos adicionais