.NET'te JSON serileştirme ve seri durumdan çıkarma (marshalling ve unmarshalling) - genel bakış
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:
- Ad alanından öznitelikler System.Runtime.Serialization .
- System.SerializableAttribute özniteliği ve ISerializable arabirimi. Bu türler yalnızca İkili ve XML serileştirme için kullanılır.
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.
Yansıma ve 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 . Yansıma 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.
