.NET'te JSON serileştirme ve seri durumdan çıkarma (marshalling ve unmarshalling) - genel bakış

  • Makale

Ad alanı, System.Text.Json JavaScript Nesne Gösterimi'ne (JSON) serileştirme ve seri durumdan çıkarma işlevleri sağlar. Serileştirme , bir nesnenin durumunu, yani özelliklerinin değerlerini depolanabilen veya iletilebilen bir forma dönüştürme işlemidir. Serileştirilmiş form, bir nesnenin ilişkili yöntemleri hakkında herhangi bir bilgi içermez. Seri durumdan çıkarma , bir nesneyi serileştirilmiş biçimden yeniden oluşturur.

Kitaplık tasarımı, System.Text.Json kapsamlı bir özellik kümesi üzerinde yüksek performansı ve düşük bellek ayırmayı vurgular. Yerleşik UTF-8 desteği, web'deki veriler ve diskteki dosyalar için en yaygın kodlama olan UTF-8 olarak kodlanmış JSON metnini okuma ve yazma sürecini iyileştirir.

Kitaplık ayrıca bellek içi belge nesne modeli (DOM) ile çalışmaya yönelik sınıflar sağlar. Bu özellik, bir JSON dosyası veya dizesindeki öğelere rastgele erişim sağlar.

Visual Basic için, kitaplığın hangi bölümlerini kullanabileceğiniz konusunda bazı sınırlamalar vardır. Daha fazla bilgi için bkz . Visual Basic desteği.

Kitaplığı alma

Kitaplık, .NET Core 3.0 ve sonraki sürümleri için paylaşılan çerçevenin bir parçası olarak yerleşiktir. Kaynak oluşturma özelliği, .NET 6 ve sonraki sürümleri için paylaşılan çerçevenin bir parçası olarak yerleşiktir.

.NET Core 3.0'dan önceki çerçeve sürümleri için NuGet paketini yükleyin System.Text.Json . Paket aşağıdakileri destekler:

  • .NET Standard 2.0 ve üzeri
  • .NET Framework 4.6.2 ve üzeri
  • .NET Core 2.1 ve üzeri
  • .NET 5 ve üzeri

Ad alanları ve API'ler

  • Ad System.Text.Json alanı tüm giriş noktalarını ve ana türleri içerir.
  • Ad alanı, System.Text.Json.Serialization serileştirmeye ve seri durumdan çıkarmaya özgü gelişmiş senaryolara ve özelleştirmeye yönelik öznitelikler ve API'ler içerir.

Bu makalede gösterilen kod örnekleri, bu ad alanlarının biri veya her ikisi için yönergeler gerektirir using .

Önemli

System.Text.Json daha önce kullanmış olabileceğiniz aşağıdaki serileştirme API'lerini desteklemez:

HttpClient ve HttpContent uzantısı yöntemleri

JSON yüklerini ağdan seri hale getirme ve seri durumdan çıkarma yaygın işlemlerdir. HttpClient ve HttpContent üzerindeki uzantı yöntemleri, bu işlemleri tek bir kod satırında yapmanıza olanak tanır. Bu uzantı yöntemleri JsonSerializerOptions için web varsayılanlarını kullanır.

Aşağıdaki örnekte ve HttpClientJsonExtensions.PostAsJsonAsynckullanımı gösterilmektedirHttpClientJsonExtensions.GetFromJsonAsync:

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

HttpContent üzerinde için System.Text.Json uzantı yöntemleri de vardır.

Düşünceler ion ile kaynak oluşturma karşılaştırması

Varsayılan olarak, System.Text.Json yansıma kullanarak çalışma zamanında serileştirme ve seri durumdan çıkarma için nesnelerin özelliklerine erişmek için ihtiyaç duyduğu meta verileri toplar. Alternatif olarak, performansı geliştirmek, System.Text.Json özel bellek kullanımını azaltmak ve uygulama boyutunu azaltan derleme kırpmayı kolaylaştırmak için C# kaynak oluşturma özelliğini kullanabilir.

Daha fazla bilgi için bkz. Düşünceler ion ve kaynak oluşturma.

Güvenlik bilgileri

tasarlarken JsonSerializerdikkate alınan güvenlik tehditleri ve bunların nasıl hafifletilebileceği hakkında bilgi için bkz System.Text.Json . Tehdit Modeli.

İş parçacığı güvenliği

Seri System.Text.Json hale getirici, iş parçacığı güvenliği göz önünde bulundurularak tasarlanmıştır. Pratikte bu, JsonSerializerOptions kilitlendikten sonra örneklerin birden çok iş parçacığı arasında güvenli bir şekilde paylaşılabildiği anlamına gelir. JsonDocument JSON değerleri için sabit ve .NET 8 ve sonraki sürümlerde iş parçacığı güvenli, DOM gösterimi sağlar.

Ek kaynaklar